home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / clang / vecpro11.zip / VECPRO.TXT < prev    next >
Text File  |  1994-12-27  |  114KB  |  6,469 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                     VectorPro(TM)
  9.  
  10.                                           
  11.  
  12.                                           
  13.  
  14.                                           
  15.  
  16.                                    Copyright 1994
  17.  
  18.                                 Vector Numerics, Inc.
  19.  
  20.                                    831 N 350 West
  21.  
  22.                           West Lafayette, IN 47906-4718 USA
  23.  
  24.  
  25.                                     Version 1.10
  26.  
  27.                                  all rights reserved
  28.  
  29.  
  30.  
  31.                    Member, Association of Shareware Professionals
  32.  
  33.  
  34.  
  35.  
  36.  
  37.        The following trademarks referenced within this manual are owned by
  38.        the following people:
  39.  
  40.        Microsoft, MS-DOS, Windows, Visual C++, MASM, QuickBASIC    
  41.        Microsoft, Inc.
  42.  
  43.        Phar Lap, DOS-Extender   Phar Lap Software, Inc.
  44.  
  45.        VectorPro, Vector Numerics, Inc.
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                               
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.        VectorPro
  74.  
  75.        Table of Contents
  76.  
  77.        Introduction                                              Intro-1
  78.          Installation                                            Intro-2
  79.          VectorPro Libraries and Files                           Intro-3
  80.          Compiler Compatibility                                  Intro-5
  81.          C vs. Assembler                                         Intro-6
  82.          Programming with VectorPro                              Intro-7
  83.          Phar Lap Compatibility                                  Intro-9
  84.  
  85.        Complex Numbers                                           Complex-1
  86.          cpx_abs             Absolute Val of a Complex Number    Complex-2
  87.          cpx_add             Add Two Complex Numbers             Complex-3
  88.          cpx_argument        Finds the Argument (Angle)          Complex-4
  89.          cpx_convert         Converts Arg:Length form to (x,y)   Complex-5
  90.          cpx_cos             Cosine of a Complex Number          Complex-6
  91.          cpx_cpx_power       Complex Number to a Complex Power   Complex-7
  92.          cpx_div             Divide Two Complex Numbers          Complex-8
  93.          cpx_exp             e to a Complex Power                Complex-9
  94.          cpx_ln              Naltural Log of a Complex Number    Complex-10
  95.          cpx_mult            Multiply Two Complex Numbers        Complex-11
  96.          cpx_power           Complex Number to a Real Power      Complex-12
  97.          cpx_sin             Sine of a Complex Number            Complex-13
  98.          cpx_sqrt            Square Root of a Complex Number     Complex-14
  99.          cpx_sub             Subtract Two Complex Numbers        Complex-15
  100.  
  101.        Interpolation                                             Inter-1
  102.          cubic_spline        Init Cubic Spline Interpolation     Inter-2
  103.          cubic_spline_int    Perform Cubic Spline Interpolation  Inter-3
  104.  
  105.        Matrix Operations                                         Matrix-1
  106.          mat_add             Add Two Matrices                    Matrix-5
  107.          mat_colop           Perform a Basic Column Operation    Matrix-6
  108.          mat_copy            Copy a Matrix                       Matrix-7
  109.          mat_determinant     Find the Determinant of a Matrix    Matrix-8
  110.          mat_errest          Estimate Error for Ax=b Solutions   Matrix-9
  111.          mat_ident           Initialize an Identity Matrix       Matrix-11
  112.          mat_inverse         Invert a Matrix                     Matrix-12
  113.          mat_inverse_errest  Invert a Matrix with Err Estimate   Matrix-13
  114.          mat_lud             LU-Decomposition                    Matrix-15
  115.          mat_mult            Multiply Two Matrices               Matrix-17
  116.          mat_rowop           Perform a Basic Row Operation       Matrix-18
  117.          mat_scalar          Multiply a Matrix by a Scalar       Matrix-19
  118.          mat_solve           Solve the Matrix Equation Ax=b      Matrix-20
  119.          mat_sub             Subtract Two Matrices               Matrix-21
  120.          mat_trace           Find the Trace of a Matrix          Matrix-22
  121.          mat_transpose       Transpose a Matrix                  Matrix-23
  122.          mat_zero            Set a Matrix to Zero                Matrix-24
  123.  
  124.        Polynomials - Real                                        Poly-1
  125.          poly_add            Add Two Polynomials                 Poly-2
  126.          poly_copy           Copy a Polynomial                   Poly-3
  127.          poly_deriv          Derivative of a Polynomial          Poly-4
  128.  
  129.                                                                   Contents - 1
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.          poly_div            Divide Two Polynomials              Poly-5
  137.          poly_eval           Evaluate a Polynomial               Poly-6
  138.          poly_integ          Integral of a Polynomial            Poly-7
  139.          poly_lin_change     Linear Change of Variable           Poly-8
  140.          poly_mult           Multiply Two Polynomials            Poly-9
  141.          poly_sub            Subtract Two Polynomials            Poly-10
  142.          poly_zero           Set a Polynomial to Zero            Poly-11
  143.  
  144.        Polynomials - Complex                                     Poly cpx-1
  145.          poly_cpx_add        Add Two Polynomials                 Poly cpx-2
  146.          poly_cpx_convert    Convert Real Poly to Complex        Poly cpx-3
  147.          poly_cpx_copy       Copy a Polynomial                   Poly cpx-4
  148.          poly_cpx_deriv      Derivative of a Polynomial          Poly cpx-5
  149.          poly_cpx_div        Divide Two Polynomials              Poly cpx-6
  150.          poly_cpx_eval       Evaluate a Polynomial               Poly cpx-7
  151.          poly_cpx_integ      Integral of a Polynomial            Poly cpx-8
  152.          poly_cpx_lin_change Linear Change of Variable           Poly cpx-9
  153.          poly_cpx_mult       Multiply Two Polynomials            Poly cpx-10
  154.          poly_cpx_root       Find a Root of a Polynomial         Poly cpx-11
  155.          poly_cpx_roots      Find All Roots of a Polynomial      Poly cpx-12
  156.          poly_cpx_sub        Subtract Two Polynomials            Poly cpx-13
  157.          poly_cpx_zero       Set a Polynomial to Zero            Poly cpx-14
  158.  
  159.        Sorting and Searching                                     Sort-1
  160.          binary_search       Binary Search on a Real Array       Sort-2
  161.          binary_search_i     Binary Search on a Real Array       Sort-3
  162.          heap_sort           Sort One or More Arrays             Sort-5
  163.  
  164.        Trigonometry                                              Trig-1
  165.          sincos              Sine and Cosine of an Angle         Trig-2
  166.  
  167.        Vectors                                                   Vectors-1
  168.          vec_add             Add Two Vectors                     Vectors-2
  169.          vec_ange            Angle Between Two Vectors           Vectors-3
  170.          vec_copy            Copy a Vector                       Vectors-4
  171.          vec_crossprod       Cross Product of  Two Vectors       Vectors-5
  172.          vec_dotprod         Dot Product of Two Vectors          Vectors-6
  173.          vec_gendotprod      Dot Product using Structures        Vectors-7
  174.          vec_magnitude       Find the Magnitude of a Vector      Vectors-8
  175.          vec_scalar          Multiply a Vector by a Scalar       Vectors-9
  176.          vec_sub             Subtract Two Vectors                Vectors-10
  177.          vec_total           Total of Vectors*Scalars            Vectors-11
  178.          vec_unit            Unit Vector Parallel to a Vector    Vectors-12
  179.          vec_zero            Set a Vector to Zero                Vectors-13
  180.  
  181.        Appendices
  182.          Vector Numerics, Inc. License Agreement for VectorPro
  183.          Support Policies
  184.          ASP Ombudsman Statement
  185.          Vector Numerics, Inc. Custom Programming Order Form
  186.          VectorPro Order From
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                   Contents - 2
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.        Introduction to VectorPro
  207.  
  208.        Congratulations on getting VectorPro, the high performance numerical
  209.        package for the Intel xxx86 family. VectorPro was written in Microsoft
  210.        Visual C++ version 1.5, and in assembly language for an extra boost in
  211.        speed. VectorPro has been exhaustively tested for accuracy, and makes
  212.        sure to flag all error and warning conditions.
  213.  
  214.        In addition, assembly language versions of the libraries provide
  215.        greater speed, accuracy, and portability between compilers than the C
  216.        version. You can use them to help build into your programs the snappy
  217.        response times today's users expect!
  218.  
  219.        This chapter introduces VectorPro, and covers general subjects you
  220.        need to know no matter which routines you actually call. The reference
  221.        section gives detailed information about each function.
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                      Intro - 1
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.        Installation
  270.  
  271.        VectorPro installation simply involves copying the libraries you want
  272.        to use off of the distribution disks into a subdirectory on your hard
  273.        disk. If you create a new directory, be sure to add it to your LIB
  274.        environment variable. You then need to copy *.H and *.INC to a
  275.        directory listed in your INCLUDE environment variable, or add the
  276.        VectorPro
  277.  
  278.        Example:
  279.  
  280.        > C:
  281.        > MD\VECPRO
  282.        > CD\VECPRO
  283.        > XCOPY A:*.*
  284.        > XCOPY A:*.*           (after inserting disk 2)
  285.  
  286.        Add the lines:
  287.  
  288.        SET LIB=%LIB%;C:\VECPRO 
  289.        SET INCLUDE=%INCLUDE%,C:\VECPRO
  290.  
  291.        to your AUTOEXEC.BAT file.
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                      Intro - 2
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.        The VectorPro Libraries and files
  336.  
  337.  
  338.        VectorPro consists of the following libraries:
  339.  
  340.            SVECPRO.LIB
  341.            SVECPROA.LIB
  342.            SVECPRO7.LIB
  343.            MVECPRO.LIB
  344.            MVECPROA.LIB
  345.            MVECPRO7.LIB
  346.            CVECPRO.LIB
  347.            CVECPROA.LIB
  348.            CVECPRO7.LIB
  349.            LVECPRO.LIB
  350.            LVECPROA.LIB
  351.            LVECPRO7.LIB
  352.            HVECPRO.LIB
  353.            HVECPROA.LIB
  354.            HVECPRO7.LIB
  355.            PVECPROA.LIB
  356.            PVECPRO7.LIB
  357.  
  358.            The first letter of the library name represents the memory model:
  359.  
  360.                S = Small or Tiny
  361.                M = Medium
  362.                C = Compact
  363.                L = Large
  364.                H = Huge
  365.                P = Phar Lap
  366.  
  367.            The last character, if there is one, represents the language
  368.            requirements of the library:
  369.  
  370.                None = compiled with the C compiler.
  371.                A = Assembled using floating point emulation.
  372.                7 = Assembled, requires xxx87 hardware.
  373.  
  374.            Note: only SVECPRO.LIB is included in the regular shareware
  375.            distribution.
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                      Intro - 3
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.            Other VectorPro Files:
  402.  
  403.            VECPRO.H        Definitions and function prototypes for VectorPro
  404.            VECPROCP.H      Definitions and function prototypes for use with
  405.                            C++
  406.  
  407.  
  408.            Files in the shareware distribution:
  409.  
  410.            VPORDER.TXT     Order form for registering VectorPro
  411.            VPCUSTOM.TXT    Order form for custom programming
  412.            LICENSE.TXT     Vector Numerics, Inc. License Agreement for
  413.                            VectorPro
  414.            OMBUDSMN.TXT    Association of Shareware Professionals Ombudsman
  415.                            Statement
  416.            SUPPORT.TXT     Vector Numerics Inc. support policy
  417.            VECPRO.TXT      The VectorPro manual
  418.            FILE_ID.DIZ     Description file for posting on BBS systems
  419.            README.TXT      The VectorPro "Read Me" file.
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.                                                                      Intro - 4
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.            Compiler Compatibility
  468.  
  469.            VectorPro was compiled with Microsoft Visual C++, version 1.5, and
  470.            may be used with either the C or the C++ sides of that compiler.
  471.            However, it does not perform any I/O to the disk or screen, and
  472.            calls only mathematical functions like sin(). It Therefore is
  473.            compatible with recent versions of Microsoft's C compilers.
  474.  
  475.            If you get LINK errors for strange undefined symbols like
  476.            __AFNLMUL, your version of the C compiler is too old. You must
  477.            either upgrade your C compiler or stop using the C versions of the
  478.            VectorPro libraries.
  479.  
  480.            The assembler versions of the libraries do not call any routines
  481.            out of the C library, except the floating point emulator. You may
  482.            therefore use them with any version of Microsoft C.
  483.  
  484.            The 7 versions of the libraries require the computer that executes
  485.            the program to have floating point capability, either as a 486DX
  486.            or with an add-on xxx87 chip. These library versions reference no
  487.            symbols defined outside of themselves, and therefore may be used
  488.            with any compiler or assembler.
  489.  
  490.            VectorPro routines may be called from other languages by following
  491.            the interfacing instructions in Microsoft's Mixed Language
  492.            Programming Guide. You may be forced to use the assembler versions
  493.            of the libraries if you get undefined symbols during LINK.
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                      Intro - 5
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.            C vs. Assembler
  534.  
  535.            The assembler versions of the VectorPro libraries implement the
  536.            same calculation logic as the C versions. They will, however,
  537.            often produce slightly different results. The difference is due to
  538.            a different use of the internal architecture of the xxx87 chip
  539.            between the C and Assembler versions.
  540.  
  541.            The xxx87 chip provides eight internal registers capable of
  542.            holding a floating point number in a special ten byte format,
  543.            which provides greater accuracy than the normal eight byte IEEE
  544.            format used by compilers. When a number is moved into the xxx87
  545.            chip, it is automatically expanded into the ten byte format, and
  546.            all subsequent computations are done using the ten byte format,
  547.            until the result is saved to memory. At that point, the result is
  548.            rounded to fit into the eight byte format again.
  549.  
  550.            Continually rounding the intermediate results of a calculation as
  551.            numbers are moved in and out of the FPU takes time, loses
  552.            accuracy, and increases the memory required for the program. By
  553.            making more effective use of the eight floating point registers,
  554.            the assembled versions can follow the same essential logic as the
  555.            C versions, while gaining an improvement in all three areas. Many
  556.            important routines run nearly twice as fast in the assembled
  557.            versions.
  558.  
  559.            As an additional gain in accuracy, the assembled versions can
  560.            store intermediate results in memory in the ten byte format, so no
  561.            rounding needs to occur when these numbers must be shifted between
  562.            memory and the FPU. You will not normally have to do anything,
  563.            since these numbers are normally saved into local memory areas
  564.            within the functions. There is a structure tenbytes defined in
  565.            VECPRO.H so you can pass arrays of ten byte areas to some
  566.            functions which require them. (The C versions of these functions
  567.            still just use eight of the ten bytes.)
  568.  
  569.            Therefore, you will, if you check, find different results between
  570.            the C and assembler versions. Both versions pass the tolerances in
  571.            the test routines here at Vector Numerics, Inc., but the assembled
  572.            versions provide the most accurate results.
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.                                                                      Intro - 6
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.            Programming with VectorPro
  600.  
  601.            Initializing:
  602.  
  603.            At the beginning of each module, include the VECPRO.H file. If you
  604.            will be using the polynomial functions, and you want to store
  605.            polynomials higher than the 20th degree, add a define statement
  606.            for the constant VP_POLYNOMIAL_MAX_ORDER before the include of
  607.            VECPRO.H.
  608.  
  609.            At the beginning of the main program, you must call the vecinit
  610.            function.
  611.  
  612.            Here is a sample main program:
  613.  
  614.            #define VP_POLYNOMIAL_MAX_ORDER 30
  615.            #include "VECPRO.H"
  616.  
  617.            etc.
  618.  
  619.            main()
  620.               {
  621.               vecinit(VP_POLYNOMIAL_MAX_ORDER);
  622.               /* We are now ready to use VECTORPRO !!! */
  623.  
  624.               etc.
  625.  
  626.               }
  627.  
  628.            The vecinit  routine must be called even if you are not using the
  629.            polynomial functions.
  630.  
  631.            VECPRO.H will also include the following C library include files
  632.            for you:
  633.  
  634.                            math.h
  635.                            float.h
  636.                            stdlib.h
  637.                            errno.h
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.                                                                      Intro - 7
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.        Calling VectorPro Functions:
  666.  
  667.            All VectorPro functions return a short integer as an error code.
  668.            The error codes possible from each function are listed as a part
  669.            of that function's documentation.
  670.  
  671.            All return values are done via pointer parameters to the
  672.            functions. Pointers are used instead of passing results through
  673.            the function value because that is faster.
  674.  
  675.            All input parameters less than or equal in size to doubles are
  676.            passed by value. Pointers to the input data are passed for complex
  677.            numbers, arrays, and structures.
  678.  
  679.            When a VectorPro routine requires temporary memory to do its job,
  680.            a pointer to the memory you want it to use must be passed. The
  681.            documentation for each function specifies the size of the memory
  682.            area needed. This approach was taken, instead of using malloc
  683.            internally, to allow you better control over the memory usage of
  684.            your program. Calling malloc internally would provide a little
  685.            cleaner interface, but would inevitably lead to situations where a
  686.            function would fail because malloc couldn't provide enough memory,
  687.            but the main program has areas under its control which could be
  688.            overwritten.
  689.  
  690.        Error Recovery:
  691.  
  692.            Special versions with names ending in _e are provided for each
  693.            VectorPro function. The _e versions return VP_INTERNAL_ERROR when
  694.            an unexpected error like using an invalid number occurs. The
  695.            normal version of the function will blow up. The _e versions have
  696.            to spend more time setting up the error trap, so you get the
  697.            choice of which version you want to use.
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.                                                                      Intro - 8
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.            Phar Lap Compatibility
  732.  
  733.            Two libraries, PVECPROA.LIB and PVECPRO7.LIB are provided for use
  734.            with the Phar Lap DOS Extender. If you have no data objects
  735.            greater than 64K, you may use any of the L libraries. You may also
  736.            link in HVECPRO.LIB if you want to use the C versions with huge
  737.            data objects.
  738.  
  739.            Be sure not to straddle the boundary between 64K segments of huge
  740.            data objects with any individual elements. Each number or complex
  741.            number must be entirely within a 64K segment. This applies to Huge
  742.            model programming as well.
  743.  
  744.            Examples:
  745.  
  746.            struct bad_struct
  747.                            {
  748.                            char c[65533];
  749.                            double vector[19];
  750.                            };
  751.  
  752.            struct good_struct
  753.                            {
  754.                            char c[65528];
  755.                            double vector[19];
  756.                            };
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.                                                                      Intro - 9
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.        COMPLEX Numbers
  801.  
  802.        VectorPro includes a large set of functions for performing operations
  803.        on complex numbers. These routines use the complex structure defined
  804.        in math.h:
  805.  
  806.        struct complex
  807.           {
  808.           double x; /* Real Part */
  809.           double y; /* Imaginary Part */
  810.           };
  811.  
  812.        All input parameters to the functions are passed as pointers.
  813.  
  814.        If this structure is and element of a huge structure, you must be sure
  815.        the imaginary part is in the same segment as the real part.
  816.  
  817.        Terms:
  818.  
  819.            absolute value: The length of the line between (0,0) and the
  820.            complex number. Also known as magnitude.
  821.  
  822.            argument: The angle made between the line from (0,0) to the
  823.            complex number and the x axis.
  824.  
  825.  
  826.  
  827.  
  828.  
  829.        VP_ACC_TLOSS and VP_ACC_PLOSS errors:
  830.  
  831.            These errors are flagged because accuracy is lost in the sin() and
  832.            cos() functions needed by various complex functions for larger
  833.            angles. This is a natural property of the sin() and cos()
  834.            functions. If these errors are returned, try to approach the
  835.            problem a different way to avoid the source of the large angles.
  836.            Subtracting a multiple of pi will not really help. The inaccuracy
  837.            arises from the operation of subtracting a large multiple of pi
  838.            from the angle. Doing this yourself only fools the function, and
  839.            leaves you with an inaccurate calculation.
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                                                    Complex - 1
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.            cpx abs
  864.  
  865.            cpx_abs(double * r, struct complex * a);
  866.            cpx_abs_e(double * r, struct complex * a);
  867.  
  868.            Sets the double r to abs(a).
  869.  
  870.  
  871.            Example:
  872.  
  873.            struct complex a;
  874.            double r;
  875.            short i;
  876.  
  877.            main()
  878.               {
  879.               a.x = 5;
  880.               a.y = -5;
  881.               if (i = cpx_abs_e(&r, &a))
  882.                  {
  883.                  /* Handle error i here */
  884.                  }
  885.               /* r = abs(a) */
  886.               }
  887.  
  888.        Possible Errors:
  889.                     NONE
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.                                                                    Complex - 2
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.        cpx add
  930.  
  931.        cpx_add(struct complex * r, struct complex * a, struct complex * b);
  932.        cpx_add_e(struct complex * r, struct complex * a, struct complex * b);
  933.  
  934.        Sets complex number r to a + b.
  935.  
  936.  
  937.        Example:
  938.  
  939.            struct complex a, b, r;
  940.            short i;
  941.  
  942.            main()
  943.               {
  944.               a.x = 17;
  945.               a.y = -8;
  946.               b.x = 2;
  947.               b.y = 6;
  948.               if (i = cpx_add_e(&r, &a, &b))
  949.                  {
  950.                  /* Handle error i here */
  951.                  }
  952.               /* r = a + b */
  953.               }
  954.  
  955.        Possible Errors:
  956.                     NONE
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.                                                                    Complex - 3
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.        cpx argument
  996.  
  997.        cpx_argument(double * r, struct complex * a);
  998.        cpx_argument_e(double * r, struct complex * a);
  999.  
  1000.        Sets the double r to argument(a).
  1001.  
  1002.  
  1003.        Example:
  1004.  
  1005.            struct complex a;
  1006.            double r;
  1007.            short i;
  1008.  
  1009.            main()
  1010.               {
  1011.               a.x = -5;
  1012.               a.y = 5;
  1013.               if (i = cpx_argument_e(&r, &a))
  1014.                  {
  1015.                  /* Handle error i here */
  1016.                  }
  1017.               /* r = argument(a) */
  1018.               }
  1019.  
  1020.        Possible Errors:
  1021.                     VP_OUT_OF_RANGE          a = (0,0)
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.                                                                    Complex - 4
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.        cpx convert
  1062.  
  1063.        cpx_convert(struct complex * r, double * abs, double arg);
  1064.        cpx_convert_e(struct complex * r, double * abs, double arg);
  1065.  
  1066.        Sets the complex number r to the (x,y) form corresponding to an
  1067.        absolute value abs and argument arg.
  1068.  
  1069.  
  1070.        Example:
  1071.  
  1072.            struct complex r;
  1073.            double abs, arg;
  1074.            short i;
  1075.  
  1076.            main()
  1077.               {
  1078.               abs = 5;
  1079.               arg = 6;
  1080.               if (i = cpx_convert_e(&r, abs, arg))
  1081.                  {
  1082.                  /* Handle error i here */
  1083.                  }
  1084.               /* r = (x,y) form of complex number at angle arg, length abs */
  1085.               }
  1086.  
  1087.        Possible Errors:
  1088.                     VP_ACC_TLOSS        |arg| > 100000000
  1089.                     VP_ACC_PLOSS        |arg| > 10000
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.                                                                    Complex - 5
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.        cpx cos
  1128.  
  1129.        cpx_cos(struct complex * r, struct complex * a);
  1130.        cpx_cos_e(struct complex * r, struct complex * a);
  1131.  
  1132.        Sets complex number r to cos(a).
  1133.  
  1134.  
  1135.        Example:
  1136.  
  1137.            struct complex a, r;
  1138.            short i;
  1139.  
  1140.            main()
  1141.               {
  1142.               a.x = -1;
  1143.               a.y = 83;
  1144.               if (i = cpx_cos_e(&r, &a)
  1145.                  {
  1146.                  /* Handle error i here */
  1147.                  }
  1148.               /* r = cos(a) */
  1149.               }
  1150.  
  1151.        Possible Errors:
  1152.                     VP_OVERFLOW              |a.x| > 706
  1153.                     VP_ACC_TLOSS             |a.y| > 100000000
  1154.                     VP_ACC_PLOSS             |a.y| > 10000
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.                                                                    Complex - 6
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.        cpx cpx power
  1194.  
  1195.        cpx_cpx_power(struct complex * r, struct complex * a,
  1196.                      struct complex * b);
  1197.        cpx_cpx_power_e(struct complex * r, struct complex * a,
  1198.                      struct complex * b);
  1199.  
  1200.        Sets complex number r to a ^ b.
  1201.  
  1202.  
  1203.        Example:
  1204.  
  1205.            struct complex a, b, r;
  1206.            short i;
  1207.  
  1208.            main()
  1209.               {
  1210.               a.x = 12;
  1211.               a.y = 54;
  1212.               b.x = 2;
  1213.               b.y = 6;
  1214.               if (i = cpx_cpx_power_e(&r, &a, &b))
  1215.                  {
  1216.                  /* Handle error i here */
  1217.                  }
  1218.               /* r = a ^ b */
  1219.               }
  1220.  
  1221.        Possible Errors:
  1222.                     VP_OUT_OF_RANGE          a = (0,0)
  1223.                     VP_OVERFLOW
  1224.                     VP_ACC_TLOSS
  1225.                     VP_ACC_PLOSS
  1226.  
  1227.        TLOSS, PLOSS, and OVERFLOW may occur when a and/or b are too large.
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.                                                                    Complex - 7
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.        cpx div
  1260.  
  1261.        cpx_div(struct complex * r, struct complex * a, struct complex * b);
  1262.        cpx_div_e(struct complex * r, struct complex * a, struct complex * b);
  1263.  
  1264.        Sets complex number r to a / b.
  1265.  
  1266.  
  1267.        Example:
  1268.  
  1269.            struct complex a, b, r;
  1270.            short i;
  1271.  
  1272.            main()
  1273.               {
  1274.               a.x = 1;
  1275.               a.y = 8;
  1276.               b.x = 12;
  1277.               b.y = 62;
  1278.               if (i = cpx_div_e(&r, &a, &b))
  1279.                  {
  1280.                  /* Handle error i here */
  1281.                  }
  1282.               /* r = a / b */
  1283.               }
  1284.  
  1285.        Possible Errors:
  1286.                     VP_DIV_BY_0
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.                                                                    Complex - 8
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.        cpx exp
  1325.  
  1326.        cpx_exp(struct complex * r, struct complex * a);
  1327.        cpx_exp_e(struct complex * r, struct complex * a);
  1328.  
  1329.        Sets complex number r to e^a.
  1330.  
  1331.  
  1332.        Example:
  1333.  
  1334.            struct complex a, r;
  1335.            short i;
  1336.  
  1337.            main()
  1338.               {
  1339.               a.x = 1;
  1340.               a.y = 8;
  1341.               if (i = cpx_exp_e(&r, &a))
  1342.                  {
  1343.                  /* Handle error i here */
  1344.                  }
  1345.               /* r = e ^ a */
  1346.               }
  1347.  
  1348.        Possible Errors:
  1349.                     VP_OVERFLOW
  1350.                     VP_ACC_TLOSS
  1351.                     VP_ACC_PLOSS
  1352.  
  1353.        TLOSS, PLOSS, and OVERFLOW may occur if a is too large.
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.                                                                    Complex - 9
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.        cpx ln
  1392.  
  1393.        cpx_ln(struct complex * r, struct complex * a);
  1394.        cpx_ln_e(struct complex * r, struct complex * a);
  1395.  
  1396.        Sets complex number r to ln(a).
  1397.  
  1398.  
  1399.        Example:
  1400.  
  1401.            struct complex a, r;
  1402.            short i;
  1403.  
  1404.            main()
  1405.               {
  1406.               a.x = 11;
  1407.               a.y = -8;
  1408.               if (i = cpx_ln_e(&r, &a))
  1409.                  {
  1410.                  /* Handle error i here */
  1411.                  }
  1412.               /* r = ln(a) */
  1413.               }
  1414.  
  1415.        Possible Errors:
  1416.                     VP_OVERFLOW              a = (0,0)
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.                                                                   Complex - 10
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.        cpx mult
  1457.  
  1458.        cpx_mult(struct complex * r, struct complex * a, struct complex * b);
  1459.        cpx_mult_e(struct complex * r, struct complex * a, struct complex * b);
  1460.  
  1461.        Sets complex number r to a * b.
  1462.  
  1463.  
  1464.        Example:
  1465.  
  1466.            struct complex a, b, r;
  1467.            short i;
  1468.  
  1469.            main()
  1470.               {
  1471.               a.x = 7;
  1472.               a.y = -4;
  1473.               b.x = 22;
  1474.               b.y = -3;
  1475.               if (i = cpx_mult_e(&r, &a, &b))
  1476.                  {
  1477.                  /* Handle error i here */
  1478.                  }
  1479.               /* r = a * b */
  1480.               }
  1481.  
  1482.        Possible Errors:
  1483.                     NONE
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.                                                                   Complex - 11
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.        cpx power
  1524.  
  1525.        cpx_power(struct complex * r, struct complex * a, double exp);
  1526.        cpx_power_e(struct complex * r, struct complex * a, double exp);
  1527.  
  1528.        Sets complex number r to a ^ exp.
  1529.  
  1530.  
  1531.        Example:
  1532.  
  1533.            struct complex a, r;
  1534.            double exp;
  1535.            short i;
  1536.  
  1537.            main()
  1538.               {
  1539.               a.x = -1;
  1540.               a.y = 83;
  1541.               exp = 4.444;
  1542.               if (i = cpx_power_e(&r, &a, exp)
  1543.                  {
  1544.                  /* Handle error i here */
  1545.                  }
  1546.               /* r = a ^ exp */
  1547.               }
  1548.  
  1549.        Possible Errors:
  1550.                     VP_PARAMETER_ERROR       a = (0,0) and exp=0
  1551.                     VP_INFINITY              a = (0,0) and exp<0
  1552.                     VP_OVERFLOW
  1553.                     VP_ACC_TLOSS
  1554.                     VP_ACC_PLOSS
  1555.  
  1556.        TLOSS, PLOSS, and OVERFLOW occur if a and/or exp are too large.
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.                                                                   Complex - 12
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.        cpx sin
  1589.  
  1590.        cpx_sin(struct complex * r, struct complex * a);
  1591.        cpx_sin_e(struct complex * r, struct complex * a);
  1592.  
  1593.        Sets complex number r to sin(a).
  1594.  
  1595.  
  1596.        Example:
  1597.  
  1598.            struct complex a, r;
  1599.            short i;
  1600.  
  1601.            main()
  1602.               {
  1603.               a.x = -1;
  1604.               a.y = 83;
  1605.               if (i = cpx_sin_e(&r, &a)
  1606.                  {
  1607.                  /* Handle error i here */
  1608.                  }
  1609.               /* r = sin(a) */
  1610.               }
  1611.  
  1612.        Possible Errors:
  1613.                     VP_OVERFLOW              |a.x| > 706
  1614.                     VP_ACC_TLOSS             |a.y| > 100000000
  1615.                     VP_ACC_PLOSS             |a.y| > 10000
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.                                                                   Complex - 13
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.        cpx sqrt
  1656.  
  1657.        cpx_sqrt(struct complex * r, struct complex * a);
  1658.        cpx_sqrt_e(struct complex * r, struct complex * a);
  1659.  
  1660.        Sets complex number r to sqrt(a).
  1661.  
  1662.  
  1663.        Example:
  1664.  
  1665.            struct complex a, r;
  1666.            short i;
  1667.  
  1668.            main()
  1669.               {
  1670.               a.x = -11;
  1671.               a.y = 5;
  1672.               if (i = cpx_sqrt_e(&r, &a)
  1673.                  {
  1674.                  /* Handle error i here */
  1675.                  }
  1676.               /* r = sqrt(a) */
  1677.               }
  1678.  
  1679.        Possible Errors:
  1680.                     NONE
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.                                                                   Complex - 14
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.        cpx sub
  1722.  
  1723.        cpx_sub(struct complex * r, struct complex * a, struct complex * b);
  1724.        cpx_sub_e(struct complex * r, struct complex * a, struct complex * b);
  1725.  
  1726.        Sets complex number r to a - b.
  1727.  
  1728.  
  1729.        Example:
  1730.  
  1731.            struct complex a, b, r;
  1732.            short i;
  1733.  
  1734.            main()
  1735.               {
  1736.               a.x = 2;
  1737.               a.y = 8;
  1738.               b.x = 2;
  1739.               b.y = 2;
  1740.               if (i = cpx_sub_e(&r, &a, &b))
  1741.                  {
  1742.                  /* Handle error i here */
  1743.                  }
  1744.               /* r = a - b */
  1745.               }
  1746.  
  1747.        Possible Errors:
  1748.                     NONE
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.                                                                   Complex - 15
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.        Interpolation
  1791.  
  1792.  
  1793.        The method of interpolation provided by VectorPro is Natural Cubic
  1794.        Spline Interpolation. The input to spline interpolation is a table of
  1795.        x and y values, where y[i] = f(x[i]), and x[i] < x[i+1]. If your data
  1796.        is in random order, you must sort it first with the heap_sort
  1797.        function. Cubic spline interpolation generates an interpolation
  1798.        function to fill in the unspecified points in the range with a
  1799.        function that:
  1800.  
  1801.           1. Equals y[i] for each i in the table,
  1802.           2. Is continuous over the entire range,
  1803.           3. Has continuous first and second derivatives over the entire
  1804.           range.
  1805.  
  1806.        Two functions are involved in performing the interpolation:
  1807.  
  1808.            cubic_spline calculates the parameters of the interpolating
  1809.            function, and need only be called once at the time the table is
  1810.            set up in memory.
  1811.  
  1812.            cubic_spline_int performs the actual interpolation, returning an
  1813.            approximate y(x) for any x within the range of the input table.
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.                                                                      Inter - 1
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.        cubic spline
  1854.  
  1855.        cubic_spline(double * x, double * y, double * y2, double * temp,
  1856.                short n);
  1857.        cubic_spline_e(double * x, double * y, double * y2, double * temp,
  1858.                short n);
  1859.  
  1860.        Computes the interpolating function parameters y2[i], for the arrays x
  1861.        and y. All the pointers are assumed to point to arrays of n elements.
  1862.        temp is needed only within the function as a work area. x, y, and y2
  1863.        must be saved for later use by cubic_spline_int.
  1864.  
  1865.        The values in x do not need to be evenly spaced.
  1866.  
  1867.  
  1868.        Example:
  1869.  
  1870.        double x[50], y[50], y2[50], temp[50];
  1871.        short i;
  1872.  
  1873.        main()
  1874.            {
  1875.            /* Input x and y here */
  1876.            if (i = cubic_spline_e(x, y, y2, temp, 50))
  1877.               {
  1878.               /* Handle error i here. */
  1879.               }
  1880.            /* The table x, y, y2 is now ready for use in interpolation. */
  1881.            }
  1882.  
  1883.  
  1884.        Possible Errors:   
  1885.                      VP_UNSORTED              the array x is unsorted
  1886.                      VP_DUPLICATES            an x value is duplicated
  1887.                      VP_PARAM_ERROR           n < 4
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.                                                                      Inter - 2
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.        cubic spline int
  1920.  
  1921.        cubic_spline_int(double * x, double * y, double * y2, short n,
  1922.                double xi, double * yi);
  1923.        cubic_spline_int_e(double * x, double * y, double * y2, short n,
  1924.                double xi, double * yi);
  1925.  
  1926.  
  1927.        This function is used to perform the actual interpolations once
  1928.        cubic_spline has set up the array y2. x, y, and y2. xi is the x value,
  1929.        yi is returned as the interpolation function evaluated at xi.
  1930.  
  1931.  
  1932.        Example:
  1933.  
  1934.        double x[50], y[50], y2[50], temp[50], xi, yi;
  1935.        short i;
  1936.  
  1937.        main()
  1938.            {
  1939.            /* Input x, xi, and y here */
  1940.            if (i = cubic_spline_e(x, y, y2, temp, 50))
  1941.               {
  1942.               /* Handle error i here. */
  1943.               }
  1944.            /* The table x, y, y2 is now ready for use in interpolation. */
  1945.            if (i = cubic_spline_int_e(x, y, y2, 50, xi, &yi))
  1946.               {
  1947.               /* Handle error i here. */
  1948.               }
  1949.            /* yi = f(xi) */
  1950.            }
  1951.  
  1952.  
  1953.        Possible errors:
  1954.                     VP_OUT_OF_RANGE          xi is outside the table
  1955.                     VP_ACC_PLOSS             xi is in the first or last
  1956.                                              interval. Some loss of
  1957.                                              accuracy may have occurred.
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.                                                                      Inter - 3
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.        MATRIX Operations
  1989.  
  1990.        Matrices may be stored in memory in two ways, which we will call the
  1991.        "malloc method" and the "parameter method". A duplicate of each matrix
  1992.        routine is supplied so that you may use the method you want. The two
  1993.        methods may be mixed within one program, but not within a single call
  1994.        to VectorPro routines. If you do need to mix arrays stored by
  1995.        different methods, there is a way to fool the parameter method
  1996.        routines into thinking a malloc array is really a parameter method
  1997.        array.
  1998.  
  1999.  
  2000.        The Malloc Method:
  2001.  
  2002.            In this method, the array elements are stored in a block of memory
  2003.            in row order, one row immediately following another. Pointer
  2004.            arithmetic is generally used to accomplish indexing the individual
  2005.            array elements. A typical use of this method would be that a
  2006.            program decides it needs an m by n array, and uses malloc to
  2007.            allocate an m*n*sizeof(double) byte block of memory to store the
  2008.            array. It then uses the pointer returned by malloc to access array
  2009.            elements.
  2010.  
  2011.            Example:
  2012.  
  2013.            short m = 5;
  2014.            short n = 6;
  2015.            double * a;
  2016.  
  2017.            main()
  2018.               {
  2019.               a = (double *) malloc(m*n*sizeof(double));
  2020.               i = mat_zero(a, m, n);
  2021.               ...
  2022.               }
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.                                                                     Matrix - 1
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.        The Parameter Method:
  2053.  
  2054.            In this method, the array is declared in a double statement, and
  2055.            preallocated a certain maximum number of rows and columns. Access
  2056.            to array elements is generally done by subscripting the array
  2057.            name. Not all of the allocated rows and columns need to be used;
  2058.            the declaration only specifies a maximum. The versions of the
  2059.            matrix routines for parameter method arrays all have names ending
  2060.            in "_p", and have one or more extra parameters which tell the
  2061.            maximum number of columns declared in the double statements
  2062.            declaring each array parameter. This method is normally used when
  2063.            the programmer knows in advance how large the arrays will need to
  2064.            be.
  2065.  
  2066.            Example:
  2067.  
  2068.            short m = 5;
  2069.            short n = 6;
  2070.            double a[10][20];   \* max of 10 rows, 20 columns *\
  2071.  
  2072.            main()
  2073.               {
  2074.               i = mat_zero_p(&a[0][0], m, n, 20);
  2075.               ...
  2076.               }
  2077.  
  2078.  
  2079.        To pass a malloc array to the _p routines, pass the actual number of
  2080.        columns in the array to the corresponding number of columns parameter.
  2081.        This effectively tells it that the maximum number of columns is in
  2082.        use, so it will not attempt to skip over any empty columns.
  2083.  
  2084.        Example:
  2085.  
  2086.            short m = 5;
  2087.            short n = 6;
  2088.            double * a;
  2089.  
  2090.            main()
  2091.               {
  2092.               a = (double *) malloc(m*n*sizeof(double));
  2093.               i = mat_zero_p(a, m, n, 6);
  2094.               ...
  2095.               }
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.                                                                     Matrix - 2
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.        The matrix routines all assume that the zero row and column of an
  2119.        array are used. If you start with element [1][1], you must use the _p
  2120.        versions. Pass a pointer to element [1][1] instead of a pointer to the
  2121.        beginning of the array.
  2122.        Example:
  2123.  
  2124.            short m = 5;
  2125.            short n = 6;
  2126.            double a[10][20];   \* max of 10 rows, 20 columns *\
  2127.  
  2128.            main()
  2129.               {
  2130.               i = mat_zero_p(@a[1][1], m, n, 20);
  2131.               ...
  2132.               }
  2133.  
  2134.  
  2135.        For simplicity, all examples in the rest of this section will assume
  2136.        the parameter method is used, and that the zero row and column are
  2137.        used.
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.                                                                     Matrix - 3
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.        Array Decomposition:
  2184.  
  2185.            VectorPro uses a technique called LU-Decomposition instead of
  2186.            relying on matrix inversion. Many are familiar with the following
  2187.            technique of solving the equation:
  2188.  
  2189.            Ax = b
  2190.  
  2191.            1. Invert A
  2192.            2. x = A-1b
  2193.  
  2194.            LU-Decomposition of the array is considerably faster, and, since
  2195.            it does not do as much computation as inversion, allows less
  2196.            opportunity for roundoff errors to accumulate into the result. The
  2197.            output of LU-Decomposition is a modified n by n array, an array of
  2198.            short integers containing one element per row of the array, and a
  2199.            short integer used to calculate the sign of the determinant. These
  2200.            three outputs must be saved and passed to other matrix routines
  2201.            for use along with the decomposed array.  A routine is provided
  2202.            which uses LU-Decomposition as an intermediate step in computing
  2203.            the inverse, if the inverse itself is needed. No loss of time is
  2204.            involved in computing the inverse in this way.
  2205.  
  2206.            Example:
  2207.  
  2208.            double a[10][10], b[10], x[10], t[10];
  2209.            short i, dsign, pivots[10];
  2210.            struct tenbytes tb[10];
  2211.  
  2212.            main()
  2213.               {
  2214.               ... /* setup data in 10 by 10 matrix a, and vector b */
  2215.               if (i = mat_lud_p(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  2216.                  {
  2217.                  /* Handle error i */
  2218.                  }
  2219.               if (i = mat_solve_p(&a[0][0], 10, pivots, x, b, 10))
  2220.                  {
  2221.                  /* Handle error i */
  2222.                  }
  2223.               /* x is now the solution of the matrix equation Ax = b */
  2224.               }
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.                                                                     Matrix - 4
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.        mat add
  2250.  
  2251.        mat_add(double * r, double * a, double * b, short nrows,
  2252.           short ncols);
  2253.        mat_add_e(double * r, double * a, double * b, short nrows,
  2254.           short ncols);
  2255.        mat_add_p(double * r, double * a, double * b, short nrows,
  2256.           short ncols, short rsiz_c, short asiz_c, short bsiz_c);
  2257.        mat_add_p_e(double * r, double * a, double * b, short nrows,
  2258.           short ncols, short rsiz_c, short asiz_c, short bsiz_c);
  2259.  
  2260.        Sets the matrix r to the sum of matrix a and matrix b. Each matrix
  2261.        must contain the same number of rows and columns.
  2262.  
  2263.  
  2264.        Example:
  2265.  
  2266.            double r[5][5], a[5][5], b[5][5];
  2267.  
  2268.            main()
  2269.               {
  2270.               ...
  2271.               if (i = mat_add_p_e(&r[0][0], &a[0][0], &b[0][0], 5, 5, 5, 5,
  2272.               5))
  2273.                  {
  2274.                  /* Handle error i */
  2275.                  }
  2276.               /* Matrix r now equals matrix a + matrix b */
  2277.               ...
  2278.               }
  2279.  
  2280.  
  2281.        Possible Errors:
  2282.  
  2283.                     NONE
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.                                                                     Matrix - 5
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.        mat colop
  2315.  
  2316.        mat_colop(double * r, short nrows, short ncols, short change_col,
  2317.                double x, short from_col);
  2318.        mat_colop_e(double * r, short nrows, short ncols, short change_col,
  2319.                double x, short from_col);
  2320.        mat_colop_p(double * r, short nrows, short ncols, short change_col,
  2321.                double x, short from_col, short rsiz_c);
  2322.        mat_colop_p_e(double * r, short nrows, short ncols, short change_col,
  2323.                double x, short from_col, short rsiz_c);
  2324.  
  2325.        Performs a basic column operation on matrix r. x times column from_col
  2326.        is added to column change_col.
  2327.  
  2328.  
  2329.        Example:
  2330.  
  2331.            double r[5][6];
  2332.  
  2333.            main()
  2334.               {
  2335.               ...
  2336.               if (i = mat_colop_p_e(&r[0][0], 5, 6, 2, (double) 4.44, 4))
  2337.                  {
  2338.                  /* Handle error i */
  2339.                  }
  2340.               /* Adds 4.44*column 4 to column 2 of matrix r */
  2341.               ...
  2342.               }
  2343.  
  2344.  
  2345.        Possible Errors:
  2346.  
  2347.                     NONE
  2348.  
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.                                                                     Matrix - 6
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.        mat copy
  2383.  
  2384.        mat_copy(double * r, double * a, short nrows, short ncols);
  2385.        mat_copy_e(double * r, double * a, short nrows, short ncols);
  2386.        mat_copy_p(double * r, double * a, short nrows, short ncols,
  2387.           short rsiz_c, short asiz_c);
  2388.        mat_copy_p_e(double * r, double * a, short nrows, short ncols,
  2389.           short rsiz_c, short asiz_c);
  2390.  
  2391.        Sets matrix r equal to matrix a. Both arrays must have the same number
  2392.        of rows and columns.
  2393.  
  2394.        Example:
  2395.  
  2396.            double r[5][5], a[5][5];
  2397.  
  2398.            main()
  2399.               {
  2400.               ...
  2401.               if (i = mat_copy_p_e(&r[0][0], &a[0][0], 5, 5, 5, 5))
  2402.                  {
  2403.                  /* Handle error i */
  2404.                  }
  2405.               /* Matrix r now equals matrix a */
  2406.               ...
  2407.               }
  2408.  
  2409.  
  2410.        Possible Errors:
  2411.  
  2412.                     NONE
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.                                                                     Matrix - 7
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.        mat determinant
  2448.  
  2449.        mat_determinant(double * r, short n, short * pivots, double * d,
  2450.                short dsign);
  2451.        mat_determinant_p(double * r, short n, short * pivots, double * d,
  2452.                short dsign, short rsiz_c);
  2453.  
  2454.  
  2455.        Finds the determinant of matrix r. It is assumed that r has been
  2456.        decomposed by mat_lud, and the pivots array and dsign were saved by
  2457.        mat_lud. Finding the determinant is very fast once the decomposition
  2458.        is done. The matrix r must be square, with n rows and columns.
  2459.  
  2460.        Example:
  2461.  
  2462.            double r[10][10], t[10], d;
  2463.            short i, dsign, pivots[10];
  2464.            struct tenbytes tb[10];
  2465.  
  2466.            main()
  2467.               {
  2468.               ... /* setup data in 10 by 10 matrix r */
  2469.               if (i = mat_lud_p_e(&r[0][0], 10, pivots, &dsign, t, tb, 10))
  2470.                  {
  2471.                  /* Handle error i */
  2472.                  }
  2473.               if (i = mat_determinant_p_e(&r[0][0], 10, pivots, &d, dsign,
  2474.               10))
  2475.                  {
  2476.                  /* Handle error i */
  2477.                  }
  2478.               /* d is now the determinant of the matrix r */
  2479.               }
  2480.  
  2481.  
  2482.        Possible Errors:
  2483.  
  2484.                     NONE*
  2485.  
  2486.  
  2487.        * Determinants may be rather large, so there is a danger of overflow
  2488.        here, especially for large matrices. It is suggested you use the _e
  2489.        version of mat_determinant if you have any doubts.
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.                                                                     Matrix - 8
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.        mat errest
  2514.  
  2515.        mat_errest(double * orig_a, double * a, short n, short * pivots,
  2516.                double * x, double * b, double * resid, double * err,
  2517.                double * tmp1, double * tmp2);
  2518.        mat_errest_e(double * orig_a, double * a, short n, short * pivots,
  2519.                double * x, double * b, double * resid, double * err,
  2520.                double * tmp1, double * tmp2);
  2521.        mat_errest_p(double * orig_a, double * a, short n, short * pivots,
  2522.                double * x, double * b, double * resid, double * err,
  2523.                double * tmp1, double * tmp2, short origa_siz_c short asiz_c);
  2524.        mat_errest_p_e(double * orig_a, double * a, short n, short * pivots,
  2525.                double * x, double * b, double * resid, double * err,
  2526.                double * tmp1, double * tmp2, short origa_siz_c short asiz_c);
  2527.  
  2528.        Error estimation of the solution for the matrix equation Ax = b. The
  2529.        matrices a and orig_a are n by n square matrices. a is the
  2530.        LU-Decomposition of the array orig_a, and the short array pivots is
  2531.        assumed to be output from mat_lud along with a.
  2532.  
  2533.        Terms used:
  2534.  
  2535.            Residual vector:  b - Axcomputed
  2536.            Error vector:     xcomputed - xexact, approximated by solving Ae =
  2537.                              residual vector
  2538.            Norm:             a single number that measures the size of a
  2539.                              vector or matrix.
  2540.                              the maximum absolute value of the elements is
  2541.                              used here.
  2542.  
  2543.        *resid is returned as norm(residual vector) / norm(b)
  2544.        *err is returned as norm(error vector) / norm(xcomputed)
  2545.        tmp1 and tmp2 must point to arrays of double with at least n elements
  2546.        each. They are used as a work area during the computations.
  2547.        Vector b is the original vector b as input to mat_solve.
  2548.        Vector x is the output of mat_solve, and is referred to as xcomputed
  2549.        above.
  2550.  
  2551.        resid and err should be as small as possible for a good solution.
  2552.        0.000001 or less should be good for most purposes. resid and err may
  2553.        be very different for ill-conditioned matrices.
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.                                                                     Matrix - 9
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.        Example:
  2580.  
  2581.        double oa[10][10], a[10][10], b[10], x[10], t[10], t2[10], resid, err;
  2582.            short i, dsign, pivots[10];
  2583.            struct tenbytes tb[10];
  2584.  
  2585.            main()
  2586.               {
  2587.               ... /* setup data in 10 by 10 matrix oa, and vector b */
  2588.               mat_copy_p(&a[0][0], &oa[0][0], 10, 10, 10, 10);
  2589.               if (i = mat_lud_p_e(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  2590.                  {
  2591.                  /* Handle error i */
  2592.                  }
  2593.               if (i = mat_solve_p_e(&a[0][0], 10, pivots, x, b, 10))
  2594.                  {
  2595.                  /* Handle error i */
  2596.                  }
  2597.               /* x is now the solution of the matrix equation Ax = b */
  2598.               if (i = mat_errest_p_e(&oa[0][0], &a[0][0], 10, pivots, x, b,
  2599.               &resid,
  2600.                   &err, t, t2, 10, 10))
  2601.                  {
  2602.                  /* Handle error i */
  2603.                  }
  2604.               if (err > 0.000001)
  2605.                  printf("WARNING: large error\n");
  2606.               }
  2607.  
  2608.  
  2609.        Possible errors:
  2610.                     NONE
  2611.  
  2612.  
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.                                                                    Matrix - 10
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.        mat_ident
  2646.  
  2647.        mat_ident(double * r, short n);
  2648.        mat_ident_e(double * r, short n);
  2649.        mat_ident_p(double * r, short n, short rsiz_c);
  2650.        mat_ident_p_e(double * r, short n, short rsiz_c);
  2651.  
  2652.        Sets r to an identity matrix. r has n rows and n columns.
  2653.  
  2654.  
  2655.        Example:
  2656.  
  2657.            double r[10][10];
  2658.            short i;
  2659.  
  2660.            main()
  2661.               {
  2662.               if (i = mat_ident_e(&r[0][0], 9, 10))
  2663.                  {
  2664.                  /* Handle error i here */
  2665.                  }
  2666.               /* r now contains a 9 by 9 identity matrix. */
  2667.               }
  2668.  
  2669.  
  2670.        Possible Errors:
  2671.                     NONE
  2672.  
  2673.  
  2674.  
  2675.  
  2676.  
  2677.  
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.                                                                    Matrix - 11
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.        mat inverse
  2712.  
  2713.        mat_inverse(double * r, double * a, short n, short * pivots,
  2714.               double * tmp1, double * tmp2);
  2715.        mat_inverse_e(double * r, double * a, short n, short * pivots,
  2716.               double * tmp1, double * tmp2);
  2717.        mat_inverse_p(double * r, double * a, short n, short * pivots,
  2718.               double * tmp1, double * tmp2, short rsiz_c, short asiz_c);
  2719.        mat_inverse_p_e(double * r, double * a, short n, short * pivots,
  2720.               double * tmp1, double * tmp2, short rsiz_c, short asiz_c);
  2721.  
  2722.        Sets r to the inverse of the original matrix a, where a and the pivots
  2723.        array are output from mat_lud for the original a. Both r and a must be
  2724.        square matrices with n rows and columns. tmp1 and tmp2 must point to
  2725.        arrays of double with at least n elements; they are used as temporary
  2726.        space during the calculation.
  2727.  
  2728.        Example:
  2729.  
  2730.            double oa[10][10], a[10][10], a_inv[10][10], t[10], t2[10];
  2731.            short i, dsign, pivots[10];
  2732.            struct tenbytes tb[10];
  2733.  
  2734.            main()
  2735.               {
  2736.               ... /* setup data in 10 by 10 matrix oa */
  2737.               mat_copy_p_e(&a[0][0], &oa[0][0], 10, 10, 10, 10);
  2738.               if (i = mat_lud_p_e(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  2739.                  {
  2740.                  /* Handle error i */
  2741.                  }
  2742.               if (i = mat_inverse_p_e(&a_inv[0][0], &a[0][0], 10, pivots, t,
  2743.               t2, 10,
  2744.                  10))
  2745.                  {
  2746.                  /* Handle error i */
  2747.                  }
  2748.               /* a_inv is now the inverse of the original matrix a */
  2749.               }
  2750.  
  2751.        Possible Errors:
  2752.                     NONE
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.                                                                    Matrix - 12
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.        mat inverse errest
  2778.  
  2779.        mat_inverse_errest(double * r, double * orig_a, double * a, short n,
  2780.           short * pivots, double * resid, double * err, double * tmp1,
  2781.           double * tmp2, double * tmp3, double * tmp4);
  2782.        mat_inverse_errest_e(double * r, double * orig_a, double * a, short n,
  2783.           short * pivots, double * resid, double * err, double * tmp1,
  2784.           double * tmp2, double * tmp3, double * tmp4);
  2785.        mat_inverse_errest_p(double * r, double * orig_a, double * a, short n,
  2786.           short * pivots, double * resid, double * err, double * tmp1,
  2787.           double * tmp2, double * tmp3, double * tmp4,
  2788.           short rsiz_c, short origa_siz_c, short asiz_c);
  2789.        mat_inverse_errest_p_e(double * r, double * orig_a, double * a,
  2790.           short n, short * pivots, double * resid, double * err,
  2791.           double * tmp1, double * tmp2, double * tmp3, double * tmp4,
  2792.           short rsiz_c, short origa_siz_c, short asiz_c);
  2793.  
  2794.  
  2795.        Sets matrix r to the inverse of matrix orig_a, where a and the pivots
  2796.        array are output from mat_lud for matrix orig_a. All three must be
  2797.        square matrices with n rows and columns.
  2798.  
  2799.        Terms used:
  2800.  
  2801.            Residual matrix:  I - AA-1computed
  2802.            Error matrix:     A-1computed - A-1exact, approximated by solving
  2803.                              AE = residual matrix
  2804.            Norm:             a single number that measures the size of a
  2805.                              vector or matrix.
  2806.                              the maximum absolute value of the elements is
  2807.                              used here.
  2808.  
  2809.        *resid is returned as norm(residual matrix) / norm(I)
  2810.        *err is returned as norm(error matrix) / norm(A-1computed)
  2811.        tmp1, tmp2, tmp3, and tmp4 must point to arrays of double with at
  2812.        least n elements each. They are used as a work area during the
  2813.        computations.
  2814.  
  2815.        resid and err should be as small as possible for a good solution.
  2816.        0.000001 or less should be good for most purposes. resid and err may
  2817.        be very different for ill-conditioned matrices.
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.                                                                    Matrix - 13
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.        Example:
  2844.  
  2845.            double oa[10][10], a[10][10], a_inv[10][10], t[10], t2[10], t3[10]
  2846.            double  resid, err, t4[10];
  2847.            short i, dsign, pivots[10];
  2848.            struct tenbytes tb[10];
  2849.  
  2850.            main()
  2851.               {
  2852.               ... /* setup data in 10 by 10 matrix oa, and vector b */
  2853.               mat_copy_p_e(&a[0][0], &oa[0][0], 10, 10, 10, 10);
  2854.               if (i = mat_lud_p_e(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  2855.                  {
  2856.                  /* Handle error i */
  2857.                  }
  2858.               if (i = mat_inverse_errest_p_e(&a_inv[0][0], &oa[0][0],
  2859.               &a[0][0],
  2860.                  10, pivots, &resid, &err, t, t2, t3, t4, 10, 10 10))
  2861.                  {
  2862.                  /* Handle error i */
  2863.                  }
  2864.               /* a_inv is now the inverse of the matrix oa */
  2865.               if (err > 0.000001)
  2866.                  printf("WARNING: large error\n");
  2867.               }
  2868.  
  2869.  
  2870.        Possible errors:
  2871.                     NONE
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.                                                                    Matrix - 14
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.        mat lud
  2909.  
  2910.        mat_lud(double * r, short n, short * pivots, short * dsign,
  2911.           double * tmp, struct tenbytes * tmp2);
  2912.        mat_lud_e(double * r, short n, short * pivots, short * dsign,
  2913.           double * tmp, struct tenbytes * tmp2);
  2914.        mat_lud_p(double * r, short n, short * pivots, short * dsign,
  2915.           double * tmp, struct tenbytes * tmp2, short rsiz_c);
  2916.        mat_lud_p_e(double * r, short n, short * pivots, short * dsign,
  2917.           double * tmp, struct tenbytes * tmp2, short rsiz_c);
  2918.  
  2919.        Performs LU-Decomposition on array r, which must be a square matrix
  2920.        with n rows and columns. If you need to preserve the original array,
  2921.        make a copy first. mat_lud also outputs an array of shorts (pivots)
  2922.        which must have at least n elements, and a short integer (dsign) used
  2923.        to calculate the sign of the determinant. One or both of these outputs
  2924.        may be required input for other VectorPro routines, along with r.
  2925.  
  2926.        tmp and tmp2 must point to arrays with at least n elements available.
  2927.        They are used as a work area.
  2928.  
  2929.        Doolittle's method is used. Doolittle's method is very closely related
  2930.        to Crout's method.
  2931.  
  2932.        Example:
  2933.  
  2934.            double a[10][10], t[10];
  2935.            short i, dsign, pivots[10];
  2936.            struct tenbytes tb[10];
  2937.  
  2938.            main()
  2939.               {
  2940.               ... /* setup data in 10 by 10 matrix a */
  2941.               if (i = mat_lud_p_e(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  2942.                  {
  2943.                  /* Handle error i */
  2944.                  }
  2945.               /* The array a is now ready for use by other matrix routines */
  2946.  
  2947.  
  2948.        Possible Errors:
  2949.                     VP_SINGULAR
  2950.                     VP_ILL_CONDITIONED
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.                                                                    Matrix - 15
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.        If the matrix was found to be singular, the decomposition halts
  2977.        immediately, and the error is returned. The array, and the short
  2978.        integer outputs will be meaningless.
  2979.  
  2980.        If the matrix was found to be ill conditioned, the decomposition is
  2981.        completed, but you must be very careful with the result. See a good
  2982.        text on numerical analysis for a full discussion of singular and ill
  2983.        conditioned matrices.
  2984.  
  2985.        A matrix A is declared ill conditioned if mat_lud feels enough error
  2986.        has accumulated in the calculation such that, if the inverse
  2987.        A-1computed were calculated:
  2988.  
  2989.           (max  | I - A*A-1computed |i,j for all i and j) > 0.000001
  2990.  
  2991.        The tolerance for a singular matrix is 0.01. 
  2992.  
  2993.        Please note that these errors flag a property of the matrix itself,
  2994.        not some artifact of the method used. If you get these errors, you
  2995.        need to carefully reformulate the problem to try to get around them. 
  2996.  
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.                                                                    Matrix - 16
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.        mat mult
  3042.  
  3043.        mat_mult(double * r, double * a, double * b, short arows,
  3044.           short acols, short bcols);
  3045.        mat_mult_e(double * r, double * a, double * b, short arows,
  3046.           short acols, short bcols);
  3047.        mat_mult_p(double * r, double * a, double * b, short arows,
  3048.           short acols, short bcols, short rsiz_c, short asiz_c, short bsiz_c);
  3049.        mat_mult_p_e(double * r, double * a, double * b, short arows,
  3050.           short acols, short bcols, short rsiz_c, short asiz_c, short bsiz_c);
  3051.  
  3052.        Sets matrix r = matrix a times matrix b.
  3053.        a has arows rows and acols columns.
  3054.        b has acols rows and bcols columns.
  3055.        r has arows rows and bcols columns.
  3056.  
  3057.        Example:
  3058.  
  3059.            double a[6][7], b[7][8], r[6][8];
  3060.            short i;
  3061.  
  3062.            main()
  3063.               {
  3064.               /* initialize arrays a and b */
  3065.               if (i = mat_mult_p_e(&r[0][0], &a[0][0], &b[0][0], 6, 7, 8, 8,
  3066.               8, 7))
  3067.                  {
  3068.                  /* Handle error i here */
  3069.                  }
  3070.               /* r now = a * b */
  3071.               }
  3072.  
  3073.  
  3074.        Possible Errors:
  3075.                     NONE
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.                                                                    Matrix - 17
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.        mat rowop
  3108.  
  3109.        mat_rowop(double * r, short nrows, short ncols, short change_row,
  3110.                double x, short from_row);
  3111.        mat_rowop_e(double * r, short nrows, short ncols, short change_row,
  3112.                double x, short from_row);
  3113.        mat_rowop_p(double * r, short nrows, short ncols, short change_row,
  3114.                double x, short from_row, short rsiz_c);
  3115.        mat_rowop_p_e(double * r, short nrows, short ncols, short change_row,
  3116.                double x, short from_row, short rsiz_c);
  3117.  
  3118.        Performs a basic row operation on matrix r. x times row from_row is
  3119.        added to row change_row.
  3120.  
  3121.  
  3122.        Example:
  3123.  
  3124.            double r[5][6];
  3125.  
  3126.            main()
  3127.               {
  3128.               ...
  3129.               if (i = mat_rowop_p_e(&r[0][0], 5, 6, 2, (double) 4.44, 4))
  3130.                  {
  3131.                  /* Handle error i */
  3132.                  }
  3133.               /* Adds 4.44*row 4 to row 2 of matrix r */
  3134.               ...
  3135.               }
  3136.  
  3137.  
  3138.        Possible Errors:
  3139.  
  3140.                     NONE
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.                                                                    Matrix - 18
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.        mat scalar
  3174.  
  3175.        mat_scalar(double * r, double * a, double x, short nrows,
  3176.           short ncols);
  3177.        mat_scalar_e(double * r, double * a, double x, short nrows,
  3178.           short ncols);
  3179.        mat_scalar_p(double * r, double * a, double x, short nrows,
  3180.           short ncols, short rsiz_c, short asiz_c);
  3181.        mat_scalar_p_e(double * r, double * a, double x, short nrows,
  3182.           short ncols, short rsiz_c, short asiz_c);
  3183.  
  3184.        Sets matrix r = scalar x times matrix a. Both r and a have nrows rows
  3185.        and ncols columns.
  3186.  
  3187.        Example:
  3188.  
  3189.            double a[6][7], r[6][7], x;
  3190.            short i;
  3191.  
  3192.            main()
  3193.               {
  3194.               /* initialize array a and scalar x */
  3195.               if (i = mat_scalar_p_e(&r[0][0], &a[0][0], x, 6, 7, 7, 7))
  3196.                  {
  3197.                  /* Handle error i here */
  3198.                  }
  3199.               /* r now = x * a */
  3200.               }
  3201.  
  3202.  
  3203.        Possible Errors:
  3204.                     NONE
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.                                                                    Matrix - 19
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.        mat solve
  3240.  
  3241.        mat_solve(double * a, short n, short * pivots, double * x,
  3242.           double * b);
  3243.        mat_solve_e(double * a, short n, short * pivots, double * x,
  3244.           double * b);
  3245.        mat_solve_p(double * a, short n, short * pivots, double * x,
  3246.           double * b, short asiz_c);
  3247.        mat_solve_p_e(double * a, short n, short * pivots, double * x,
  3248.           double * b, short asiz_c);
  3249.  
  3250.        Solves the matrix equation Ax=b, where a is a square matrix with n
  3251.        rows and n columns, and x and b are vectors with n dimensions. The a
  3252.        input to this routine must have been run through mat_lud first, and
  3253.        the pivots array output by mat_lud must be preserved for use here.
  3254.  
  3255.        Example:
  3256.  
  3257.            double a[10][10], b[10], x[10], t[10];
  3258.            short i, dsign, pivots[10];
  3259.            struct tenbytes tb[10];
  3260.  
  3261.            main()
  3262.               {
  3263.               ... /* setup data in 10 by 10 matrix a, and vector b */
  3264.               if (i = mat_lud_p_e(&a[0][0], 10, pivots, &dsign, t, tb, 10))
  3265.                  {
  3266.                  /* Handle error i */
  3267.                  }
  3268.               if (i = mat_solve_p_e(&a[0][0], 10, pivots, x, b, 10))
  3269.                  {
  3270.                  /* Handle error i */
  3271.                  }
  3272.               /* x is now the solution of the matrix equation Ax = b */
  3273.            }
  3274.  
  3275.  
  3276.        Possible Errors:
  3277.                     NONE
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.                                                                    Matrix - 20
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.        mat sub
  3306.  
  3307.        mat_sub(double * r, double * a, double * b, short nrows,
  3308.           short ncols);
  3309.        mat_sub_e(double * r, double * a, double * b, short nrows,
  3310.           short ncols);
  3311.        mat_sub_p(double * r, double * a, double * b, short nrows,
  3312.           short ncols, short rsiz_c, short asiz_c, short bsiz_c);
  3313.        mat_sub_p_e(double * r, double * a, double * b, short nrows,
  3314.           short ncols, short rsiz_c, short asiz_c, short bsiz_c);
  3315.  
  3316.        Sets the matrix r to the difference of matrix a and matrix b. Each
  3317.        matrix must contain the same number of rows and columns.
  3318.  
  3319.  
  3320.        Example:
  3321.  
  3322.            double r[5][5], a[5][5], b[5][5];
  3323.  
  3324.            main()
  3325.               {
  3326.               ...
  3327.               if (i = mat_sub_p_e(&r[0][0], &a[0][0], &b[0][0], 5, 5, 5, 5,
  3328.               5))
  3329.                  {
  3330.                  /* Handle error i */
  3331.                  }
  3332.               /* Matrix r now equals matrix a - matrix b */
  3333.               ...
  3334.               }
  3335.  
  3336.  
  3337.        Possible Errors:
  3338.  
  3339.                     NONE
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.  
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.                                                                    Matrix - 21
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.        mat trace
  3372.  
  3373.        mat_trace(double * t, double * a, short n);
  3374.        mat_trace_e(double * t, double * a, short n);
  3375.        mat_trace_p(double * t, double * a, short n, short asiz_c);
  3376.        mat_trace_p_e(double * t, double * a, short n, short asiz_c);
  3377.  
  3378.        Returns the trace of the n by n matrix a in t.
  3379.  
  3380.        Example:
  3381.  
  3382.            double t, a[6][6];
  3383.            short i;
  3384.  
  3385.            main()
  3386.               {
  3387.               /* Initialize array a here */
  3388.               if (i = mat_trace_p_e(&t, &a[0][0], 6, 6))
  3389.                  {
  3390.                  /* Handle error i here */
  3391.                  }
  3392.               /* t is now equal to the trace of matrix a */
  3393.               }
  3394.  
  3395.        Possible Errors:
  3396.                     NONE
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.                                                                    Matrix - 22
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.        mat transpose
  3438.  
  3439.        mat_transpose(double * r, short nrows, short ncols, double * a);
  3440.        mat_transpose_e(double * r, short nrows, short ncols, double * a);
  3441.        mat_transpose_p(double * r, short nrows, short ncols, double * a,
  3442.               short rsiz_c, short asiz_c);
  3443.        mat_transpose_p_e(double * r, short nrows, short ncols, double * a,
  3444.               short rsiz_c, short asiz_c);
  3445.  
  3446.        Sets matrix r to be the transpose of matrix a.
  3447.        Matrix a has nrows rows and ncols columns, while r has ncols rows and
  3448.        nrows columns.
  3449.  
  3450.        Example:
  3451.  
  3452.            double a[6][8], r[8][6];
  3453.            short i;
  3454.  
  3455.            main()
  3456.               {
  3457.               /* Initialize 6 by 8 matrix a here */
  3458.               if (i = mat_transpose_p_e(&r[0][0], 6, 8, &a[0][0], 6, 8))
  3459.                  {
  3460.                  /* Handle error i here */
  3461.                  }
  3462.               /* r now = transpose(a) */
  3463.               }
  3464.  
  3465.        Possible Errors:
  3466.                     NONE
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.                                                                    Matrix - 23
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.        mat zero
  3504.  
  3505.        mat_zero(double * r, short n);
  3506.        mat_zero_e(double * r, short n);
  3507.        mat_zero_p(double * r, short n, short rsiz_c);
  3508.        mat_zero_p_e(double * r, short n, short rsiz_c);
  3509.  
  3510.        Sets r to an zero matrix. r has n rows and n columns.
  3511.  
  3512.  
  3513.        Example:
  3514.  
  3515.            double r[10][10];
  3516.            short i;
  3517.  
  3518.            main()
  3519.               {
  3520.               if (i = mat_zero_p_e(&r[0][0], 9, 10))
  3521.                  {
  3522.                  /* Handle error i here */
  3523.                  }
  3524.               /* r now contains a 9 by 9 zero matrix. */
  3525.               }
  3526.  
  3527.  
  3528.        Possible Errors:
  3529.                     NONE
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.                                                                    Matrix - 24
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.        POLYNOMIAL Functions
  3572.  
  3573.  
  3574.        The polynomial functions use the structure poly, which is defined in
  3575.        the VECPRO.H file.
  3576.  
  3577.        They also make use of the constant VP_POLYNOMIAL_MAX_ORDER. The
  3578.        default value for MAX_ORDER is 20, meaning each polynomial may contain
  3579.        up to the x20 term. If you want to define a different MAX_ORDER, 30,
  3580.        for example, add the following line to all your source files before
  3581.        including VECPRO.H:
  3582.  
  3583.        #define    VP_POLYNOMIAL_MAX_ORDER     30
  3584.  
  3585.        The structure poly is defined as follows:
  3586.  
  3587.        struct poly
  3588.           {
  3589.           short order;
  3590.           char waste[6];
  3591.           double co[VP_POLYNOMIAL_MAX_ORDER+1];
  3592.           }
  3593.  
  3594.        The waste array is there to be sure the coefficient array is aligned
  3595.        efficiently in memory.
  3596.  
  3597.        order contains the current order of the polynomial, and may range from
  3598.        0 to VP_POLYNOMIAL_MAX_ORDER.
  3599.  
  3600.        co contains the coefficients of the polynomial:
  3601.  
  3602.           polynomial = co[0] + co[1]x + co[2]x2  etc.
  3603.  
  3604.  
  3605.        Note: For generality, the root finding routines work on complex
  3606.        polynomials. Use the poly_cpx_convert function to convert real
  3607.        polynomials to complex. poly_cpx_convert is documented in the complex
  3608.        polynomials chapter.
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.                                                                       Poly - 1
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.        poly add
  3636.  
  3637.        poly_add(struct poly * r, struct poly * a, struct poly * b);
  3638.        poly_add_e(struct poly * r, struct poly * a, struct poly * b);
  3639.  
  3640.        Sets polynomial r = polynomial a + polynomial b.
  3641.        r.order becomes max(a.order, b.order).
  3642.  
  3643.  
  3644.        Example:
  3645.  
  3646.        struct poly r;
  3647.        struct poly a;
  3648.        struct poly b;
  3649.        short i;
  3650.  
  3651.        main()
  3652.            {
  3653.            /* Initialize polynomials a and b here */
  3654.            if (i = poly_add_e(&r, &a, &b))
  3655.               {
  3656.               /* Handle error i here */
  3657.               }
  3658.            /* r = a + b */
  3659.            }
  3660.  
  3661.  
  3662.        Possible errors:
  3663.                     VP_OVERFLOW    attempted to make r.order too large.
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.  
  3673.  
  3674.  
  3675.  
  3676.  
  3677.  
  3678.  
  3679.  
  3680.  
  3681.  
  3682.  
  3683.  
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.                                                                       Poly - 2
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.        poly copy
  3702.  
  3703.        poly_copy(struct poly * r, struct poly * a);
  3704.        poly_copy_e(struct poly * r, struct poly * a);
  3705.  
  3706.        Sets polynomial r = polynomial a.
  3707.        r.order becomes a.order.
  3708.  
  3709.  
  3710.        Example:
  3711.  
  3712.        struct poly r;
  3713.        struct poly a;
  3714.        short i;
  3715.  
  3716.        main()
  3717.            {
  3718.            /* Initialize polynomial a here */
  3719.            if (i = poly_copy_e(&r, &a))
  3720.               {
  3721.               /* Handle error i here */
  3722.               }
  3723.            /* r = a */
  3724.            }
  3725.  
  3726.  
  3727.        Possible errors:
  3728.                     VP_OVERFLOW    attempted to make r.order too large.
  3729.  
  3730.  
  3731.  
  3732.  
  3733.  
  3734.  
  3735.  
  3736.  
  3737.  
  3738.  
  3739.  
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.                                                                       Poly - 3
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.        poly deriv
  3768.  
  3769.        poly_deriv(struct poly * r, struct poly * a);
  3770.        poly_deriv_e(struct poly * r, struct poly * a);
  3771.  
  3772.        Sets polynomial r = derivative(polynomial a).
  3773.        r.order becomes a.order - 1, unless a.order was already zero..
  3774.  
  3775.  
  3776.        Example:
  3777.  
  3778.        struct poly r;
  3779.        struct poly a;
  3780.        short i;
  3781.  
  3782.        main()
  3783.            {
  3784.            /* Initialize polynomial a here */
  3785.            if (i = poly_deriv_e(&r, &a))
  3786.               {
  3787.               /* Handle error i here */
  3788.               }
  3789.            /* r = derivative(a) */
  3790.            }
  3791.  
  3792.  
  3793.        Possible errors:
  3794.                     NONE
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.                                                                       Poly - 4
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.        poly div
  3834.  
  3835.        poly_div(struct poly * r, struct poly * a, struct poly * b,
  3836.               struct poly * m);
  3837.        poly_div_e(struct poly * r, struct poly * a, struct poly * b,
  3838.               struct poly * m);
  3839.  
  3840.        Sets polynomial r = polynomial a / polynomial b.
  3841.        Any remainder is set into polynomial m.
  3842.  
  3843.  
  3844.        Example:
  3845.  
  3846.        struct poly r;
  3847.        struct poly a;
  3848.        struct poly b;
  3849.        struct poly m;
  3850.        short i;
  3851.  
  3852.        main()
  3853.            {
  3854.            /* Initialize polynomials a and b here */
  3855.            if (i = poly_div_e(&r, &a, &b, &m))
  3856.               {
  3857.               /* Handle error i here */
  3858.               }
  3859.            /* r = a / b, remainder is in m */
  3860.            }
  3861.  
  3862.  
  3863.        Possible errors:
  3864.                     VP_DIV_BY_0
  3865.  
  3866.  
  3867.  
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.                                                                       Poly - 5
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.        poly eval
  3900.  
  3901.        poly_eval(double * r, double x, struct poly * a);
  3902.        poly_eval_e(double * r, double x, struct poly * a);
  3903.  
  3904.        Sets r = polynomial a(x).
  3905.  
  3906.  
  3907.        Example:
  3908.  
  3909.        double r, x;
  3910.        struct poly a;
  3911.        short i;
  3912.  
  3913.        main()
  3914.            {
  3915.            /* Initialize polynomial a and x here */
  3916.            if (i = poly_eval_e(&r, x, &a))
  3917.               {
  3918.               /* Handle error i here */
  3919.               }
  3920.            /* r = a(x) */
  3921.            }
  3922.  
  3923.  
  3924.        Possible errors:
  3925.                     NONE
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.                                                                       Poly - 6
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.        poly integ
  3966.  
  3967.        poly_integ(struct poly * r, struct poly * a);
  3968.        poly_integ_e(struct poly * r, struct poly * a);
  3969.  
  3970.        Sets polynomial r = integral(polynomial a).
  3971.        r.order becomes a.order + 1.
  3972.  
  3973.  
  3974.        Example:
  3975.  
  3976.        struct poly r;
  3977.        struct poly a;
  3978.        short i;
  3979.  
  3980.        main()
  3981.            {
  3982.            /* Initialize polynomials a and b here */
  3983.            if (i = poly_integ_e(&r, &a))
  3984.               {
  3985.               /* Handle error i here */
  3986.               }
  3987.            /* r = integral(a) */
  3988.            }
  3989.  
  3990.  
  3991.        Possible errors:
  3992.                     VP_OVERFLOW    attempted to make r.order too large.
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.                                                                       Poly - 7
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.        poly lin change
  4032.  
  4033.        poly_lin_change(struct poly * r, struct poly * a, double ycoeff,
  4034.                 double c, double * temp1, double * temp2);
  4035.        poly_lin_change_e(struct poly * r, struct poly * a, double ycoeff,
  4036.                 double c, double * temp1, double * temp2);
  4037.  
  4038.  
  4039.        Makes a new polynomial r(y) = polynomial a(x),
  4040.                               where x = ycoeff*y + c.
  4041.        r.order becomes a.order.
  4042.        temp1 and temp2 must point to arrays of complex with at least
  4043.        VP_POLYNOMIAL_MAX_ORDER elements. They are used as a work area.
  4044.  
  4045.  
  4046.        Example:
  4047.  
  4048.        struct poly r;
  4049.        struct poly a;
  4050.        double ycoeff, c;
  4051.        double temp1[VP_POLYNOMIAL_MAX_ORDER + 1];
  4052.        double temp2[VP_POLYNOMIAL_MAX_ORDER + 1];
  4053.        short i;
  4054.  
  4055.        main()
  4056.            {
  4057.            /* Initialize polynomial a, ycoeff, and c here */
  4058.            if (i = poly_lin_change_e(&r, &a, ycoeff, c, temp1, temp2))
  4059.               {
  4060.               /* Handle error i here */
  4061.               }
  4062.            /* r(y) = a(x), where x = ycoeff*y + c */
  4063.            }
  4064.  
  4065.  
  4066.        Possible errors:
  4067.                     VP_OVERFLOW         attempted to make r.order too large.
  4068.                     VP_PARAM_ERROR      ycoeff was zero.
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.                                                                       Poly - 8
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.        poly mult
  4098.  
  4099.        poly_mult(struct poly * r, struct poly * a, struct poly * b);
  4100.        poly_mult_e(struct poly * r, struct poly * a, struct poly * b);
  4101.  
  4102.        Sets polynomial r = polynomial a * polynomial b.
  4103.        r.order becomes a.order + b.order.
  4104.  
  4105.  
  4106.        Example:
  4107.  
  4108.        struct poly r;
  4109.        struct poly a;
  4110.        struct poly b;
  4111.        short i;
  4112.  
  4113.        main()
  4114.            {
  4115.            /* Initialize polynomials a and b here */
  4116.            if (i = poly_mult_e(&r, &a, &b))
  4117.               {
  4118.               /* Handle error i here */
  4119.               }
  4120.            /* r = a * b */
  4121.            }
  4122.  
  4123.  
  4124.        Possible errors:
  4125.                     VP_OVERFLOW    attempted to make r.order too large.
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.  
  4149.  
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.                                                                       Poly - 9
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.        poly sub
  4164.  
  4165.        poly_sub(struct poly * r, struct poly * a, struct poly * b);
  4166.        poly_sub_e(struct poly * r, struct poly * a, struct poly * b);
  4167.  
  4168.        Sets polynomial r = polynomial a - polynomial b.
  4169.        r.order becomes max(a.order, b.order).
  4170.  
  4171.  
  4172.        Example:
  4173.  
  4174.        struct poly r;
  4175.        struct poly a;
  4176.        struct poly b;
  4177.        short i;
  4178.  
  4179.        main()
  4180.            {
  4181.            /* Initialize polynomials a and b here */
  4182.            if (i = poly_sub_e(&r, &a, &b))
  4183.               {
  4184.               /* Handle error i here */
  4185.               }
  4186.            /* r = a - b */
  4187.            }
  4188.  
  4189.  
  4190.        Possible errors:
  4191.                     VP_OVERFLOW    attempted to make r.order too large.
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.                                                                      Poly - 10
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.        poly zero
  4230.  
  4231.        poly_zero(struct poly * r);
  4232.        poly_zero_e(struct poly * r);
  4233.  
  4234.        Sets polynomial r = 0.
  4235.        r.order becomes 0, co[0] becomes 0.
  4236.  
  4237.  
  4238.        Example:
  4239.  
  4240.        struct poly r;
  4241.        short i;
  4242.  
  4243.        main()
  4244.            {
  4245.            if (i = poly_zero_e(&r))
  4246.               {
  4247.               /* Handle error i here */
  4248.               }
  4249.            /* r = 0 */
  4250.            }
  4251.  
  4252.  
  4253.        Possible errors:
  4254.                     NONE
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.                                                                      Poly - 11
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.        COMPLEX POLYNOMIAL Functions
  4298.  
  4299.  
  4300.        The complex polynomial functions use the structure polyx, which is
  4301.        defined in the VECPRO.H file.
  4302.  
  4303.        They also make use of the constant VP_POLYNOMIAL_MAX_ORDER. The
  4304.        default value for MAX_ORDER is 20, meaning each complex polynomial may
  4305.        contain up to the x20 term. If you want to define a different
  4306.        MAX_ORDER, 30, for example, add the following line to all your source
  4307.        files before including VECPRO.H:
  4308.  
  4309.        #define    VP_POLYNOMIAL_MAX_ORDER     30
  4310.  
  4311.        The structure polyx is defined as follows:
  4312.  
  4313.        struct polyx
  4314.           {
  4315.           short order;
  4316.           char waste[6];
  4317.           struct complex co[VP_POLYNOMIAL_MAX_ORDER+1];
  4318.           }
  4319.  
  4320.        The waste array is there to be sure the coefficient array is aligned
  4321.        efficiently in memory.
  4322.  
  4323.        order contains the current order of the complex polynomial, and may
  4324.        range from 0 to VP_POLYNOMIAL_MAX_ORDER.
  4325.  
  4326.        co contains the coefficients of the complex polynomial:
  4327.  
  4328.           complex polynomial = co[0] + co[1]x + co[2]x2  etc.
  4329.  
  4330.  
  4331.  
  4332.  
  4333.  
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.                                                                   Poly cpx - 1
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.        poly cpx add
  4362.  
  4363.        poly_cpx_add(struct polyx * r, struct polyx * a, struct polyx * b);
  4364.        poly_cpx_add_e(struct polyx * r, struct polyx * a, struct polyx * b);
  4365.  
  4366.        Sets complex polynomial r = complex polynomial a + complex polynomial
  4367.        b.
  4368.        r.order becomes max(a.order, b.order).
  4369.  
  4370.  
  4371.        Example:
  4372.  
  4373.        struct polyx r;
  4374.        struct polyx a;
  4375.        struct polyx b;
  4376.        short i;
  4377.  
  4378.        main()
  4379.            {
  4380.            /* Initialize complex polynomials a and b here */
  4381.            if (i = poly_cpx_add_e(&r, &a, &b))
  4382.               {
  4383.               /* Handle error i here */
  4384.               }
  4385.            /* r = a + b */
  4386.            }
  4387.  
  4388.  
  4389.        Possible errors:
  4390.                     VP_OVERFLOW    attempted to make r.order too large.
  4391.  
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.                                                                   Poly cpx - 2
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.        poly cpx convert
  4428.  
  4429.        poly_cpx_convert(struct polyx * r, struct polyx* a);
  4430.        poly_cpx_convert_e(struct polyx * r, struct poly * a);
  4431.  
  4432.        Sets complex polynomial r = real polynomial a.
  4433.        r.order becomes a.order.
  4434.  
  4435.  
  4436.        Example:
  4437.  
  4438.        struct polyx r;
  4439.        struct poly a;
  4440.        short i;
  4441.  
  4442.        main()
  4443.            {
  4444.            /* Initialize polynomial a here */
  4445.            if (i = poly_cpx_convert_e(&r, &a))
  4446.               {
  4447.               /* Handle error i here */
  4448.               }
  4449.            /* r = a */
  4450.            }
  4451.  
  4452.  
  4453.        Possible errors:
  4454.                     VP_OVERFLOW    attempted to make r.order too large.
  4455.  
  4456.  
  4457.  
  4458.  
  4459.  
  4460.  
  4461.  
  4462.  
  4463.  
  4464.  
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.                                                                   Poly cpx - 3
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.        poly cpx copy
  4494.  
  4495.        poly_cpx_copy(struct polyx * r, struct polyx * a);
  4496.        poly_cpx_copy_e(struct polyx * r, struct polyx * a);
  4497.  
  4498.        Sets complex polynomial r = complex polynomial a.
  4499.        r.order becomes a.order.
  4500.  
  4501.  
  4502.        Example:
  4503.  
  4504.        struct polyx r;
  4505.        struct polyx a;
  4506.        short i;
  4507.  
  4508.        main()
  4509.            {
  4510.            /* Initialize complex polynomial a here */
  4511.            if (i = poly_cpx_copy_e(&r, &a))
  4512.               {
  4513.               /* Handle error i here */
  4514.               }
  4515.            /* r = a */
  4516.            }
  4517.  
  4518.  
  4519.        Possible errors:
  4520.                     VP_OVERFLOW    attempted to make r.order too large.
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.  
  4533.  
  4534.  
  4535.  
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.                                                                   Poly cpx - 4
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.        poly cpx deriv
  4560.  
  4561.        poly_cpx_deriv(struct polyx * r, struct polyx * a);
  4562.        poly_cpx_deriv_e(struct polyx * r, struct polyx * a);
  4563.  
  4564.        Sets complex polynomial r = derivative(complex polynomial a).
  4565.        r.order becomes a.order - 1, unless a.order was already zero..
  4566.  
  4567.  
  4568.        Example:
  4569.  
  4570.        struct polyx r;
  4571.        struct polyx a;
  4572.        short i;
  4573.  
  4574.        main()
  4575.            {
  4576.            /* Initialize complex polynomial a here */
  4577.            if (i = poly_cpx_deriv_e(&r, &a))
  4578.               {
  4579.               /* Handle error i here */
  4580.               }
  4581.            /* r = derivative(a) */
  4582.            }
  4583.  
  4584.  
  4585.        Possible errors:
  4586.                     NONE
  4587.  
  4588.  
  4589.  
  4590.  
  4591.  
  4592.  
  4593.  
  4594.  
  4595.  
  4596.  
  4597.  
  4598.  
  4599.  
  4600.  
  4601.  
  4602.  
  4603.  
  4604.  
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.  
  4616.  
  4617.                                                                   Poly cpx - 5
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.        poly cpx div
  4626.  
  4627.        poly_cpx_div(struct polyx * r, struct polyx * a, struct polyx * b,
  4628.               struct polyx * m);
  4629.        poly_cpx_div_e(struct polyx * r, struct polyx * a, struct polyx * b,
  4630.               struct polyx * m);
  4631.  
  4632.        Sets complex polynomial r = complex polynomial a / complex polynomial
  4633.        b.
  4634.        Any remainder is set into complex polynomial m.
  4635.  
  4636.  
  4637.        Example:
  4638.  
  4639.        struct polyx r;
  4640.        struct polyx a;
  4641.        struct polyx b;
  4642.        struct polyx m;
  4643.        short i;
  4644.  
  4645.        main()
  4646.            {
  4647.            /* Initialize complex polynomials a and b here */
  4648.            if (i = poly_cpx_div_e(&r, &a, &b, &m))
  4649.               {
  4650.               /* Handle error i here */
  4651.               }
  4652.            /* r = a / b, remainder is in m */
  4653.            }
  4654.  
  4655.  
  4656.        Possible errors:
  4657.                     VP_DIV_BY_0
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.                                                                   Poly cpx - 6
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.        poly cpx eval
  4692.  
  4693.        poly_cpx_eval(struct complex * r, struct complex * x,
  4694.                struct polyx * a);
  4695.        poly_cpx_eval_e(struct complex * r, struct complex * x,
  4696.                struct polyx * a);
  4697.  
  4698.        Sets r = complex polynomial a(x).
  4699.  
  4700.  
  4701.        Example:
  4702.  
  4703.        struct complex r, x;
  4704.        struct polyx a;
  4705.        short i;
  4706.  
  4707.        main()
  4708.            {
  4709.            /* Initialize complex polynomial a and x here */
  4710.            if (i = poly_cpx_eval_e(&r, &x, &a))
  4711.               {
  4712.               /* Handle error i here */
  4713.               }
  4714.            /* r = a(x) */
  4715.            }
  4716.  
  4717.  
  4718.        Possible errors:
  4719.                     NONE
  4720.  
  4721.  
  4722.  
  4723.  
  4724.  
  4725.  
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.  
  4735.  
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.  
  4747.  
  4748.  
  4749.                                                                   Poly cpx - 7
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.        poly cpx integ
  4758.  
  4759.        poly_cpx_integ(struct polyx * r, struct polyx * a);
  4760.        poly_cpx_integ_e(struct polyx * r, struct polyx * a);
  4761.  
  4762.        Sets complex polynomial r = integral(complex polynomial a).
  4763.        r.order becomes a.order + 1.
  4764.  
  4765.  
  4766.        Example:
  4767.  
  4768.        struct polyx r;
  4769.        struct polyx a;
  4770.        short i;
  4771.  
  4772.        main()
  4773.            {
  4774.            /* Initialize complex polynomials a and b here */
  4775.            if (i = poly_cpx_integ_e(&r, &a))
  4776.               {
  4777.               /* Handle error i here */
  4778.               }
  4779.            /* r = integral(a) */
  4780.            }
  4781.  
  4782.  
  4783.        Possible errors:
  4784.                     VP_OVERFLOW    attempted to make r.order too large.
  4785.  
  4786.  
  4787.  
  4788.  
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.  
  4795.  
  4796.  
  4797.  
  4798.  
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.                                                                   Poly cpx - 8
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.        poly cpx lin change
  4824.  
  4825.        poly_cpx_lin_change(struct polyx * r, struct polyx * a,
  4826.                 struct complex ycoeff, struct complex c,
  4827.                 struct complex * temp1, struct complex * temp2);
  4828.        poly_cpx_lin_change_e(struct polyx * r, struct polyx * a,
  4829.                 struct complex ycoeff, struct complex c,
  4830.                 struct complex * temp1, struct complex * temp2);
  4831.  
  4832.  
  4833.        Makes a new complex polynomial r(y) = complex polynomial a(x),
  4834.                               where x = ycoeff*y + c.
  4835.  
  4836.        r.order becomes a.order.
  4837.        temp1 and temp2 must point to arrays of complex with at least
  4838.        VP_POLYNOMIAL_MAX_ORDER elements. They are used as a work area.
  4839.  
  4840.  
  4841.        Example:
  4842.  
  4843.        struct polyx r;
  4844.        struct polyx a;
  4845.        struct complex ycoeff, c;
  4846.        struct complex temp1[VP_POLYNOMIAL_MAX_ORDER + 1];
  4847.        struct complex temp2[VP_POLYNOMIAL_MAX_ORDER + 1];
  4848.        short i;
  4849.  
  4850.        main()
  4851.            {
  4852.            /* Initialize complex polynomial a, ycoeff, and c here */
  4853.            if (i = poly_cpx_lin_change_e(&r, &a, &ycoeff, &c, temp1, temp2))
  4854.               {
  4855.               /* Handle error i here */
  4856.               }
  4857.            /* r(y) = a(x), where x = ycoeff*y + c */
  4858.            }
  4859.  
  4860.  
  4861.        Possible errors:
  4862.                     VP_OVERFLOW         attempted to make r.order too large.
  4863.                     VP_PARAM_ERROR      ycoeff was zero.
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.                                                                   Poly cpx - 9
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.        poly cpx mult
  4890.  
  4891.        poly_cpx_mult(struct polyx * r, struct polyx * a, struct polyx * b);
  4892.        poly_cpx_mult_e(struct polyx * r, struct polyx * a, struct polyx * b);
  4893.  
  4894.        Sets complex polynomial r = complex polynomial a * complex polynomial
  4895.        b.
  4896.        r.order becomes a.order + b.order.
  4897.  
  4898.  
  4899.        Example:
  4900.  
  4901.        struct polyx r;
  4902.        struct polyx a;
  4903.        struct polyx b;
  4904.        short i;
  4905.  
  4906.        main()
  4907.            {
  4908.            /* Initialize complex polynomials a and b here */
  4909.            if (i = poly_cpx_mult_e(&r, &a, &b))
  4910.               {
  4911.               /* Handle error i here */
  4912.               }
  4913.            /* r = a * b */
  4914.            }
  4915.  
  4916.  
  4917.        Possible errors:
  4918.                     VP_OVERFLOW    attempted to make r.order too large.
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.  
  4947.                                                                  Poly cpx - 10
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.        poly cpx root
  4956.  
  4957.        poly_cpx_root(struct complex * r, double * c, struct polyx * a,
  4958.                struct complex * guess);
  4959.        poly_cpx_root_e(struct complex * r, double * c, struct polyx * a,
  4960.                struct complex * guess);
  4961.  
  4962.  
  4963.        Finds one root of the polynomial a, and returns it in r. The search
  4964.        for the root is begun at guess.
  4965.  
  4966.        The condition number of the root is returned in c. It indicates the
  4967.        amount of error to be expected in the determination of the root. The
  4968.        smaller the condition number is, the more accurate the calculated root
  4969.        is. The condition number may range from one on up. If it gets above
  4970.        1014, the calculated root is worthless. It should be noted that the
  4971.        condition number measures how sensitive the value of the calculated
  4972.        root is to error in the coefficient array, and thus is a property of
  4973.        the polynomial itself, not of the calculation method. If a large
  4974.        condition number is returned, you need to reformulate your problem to
  4975.        avoid it.
  4976.  
  4977.  
  4978.        Example:
  4979.  
  4980.        struct polyx a;
  4981.        struct complex r, guess;
  4982.        double c;
  4983.        short i;
  4984.        main()
  4985.            {
  4986.            /* Initialize complex polynomial a, and guess here. */
  4987.            if (i = poly_cpx_root_e(&r, &c, &a, &guess))
  4988.               {
  4989.               /* Handle error i here */
  4990.               }
  4991.            /* We have now found a root: r */
  4992.            }
  4993.  
  4994.  
  4995.            Possible Errors:
  4996.                          VP_ILL_CONDITIONED       c > 1010
  4997.                          VP_PARAM_ERROR           a.order = 0
  4998.                          VP_NO_CONVERGENCE
  4999.  
  5000.            Lagurre's Method is used.
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.  
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.  
  5013.                                                                  Poly cpx - 11
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.        poly cpx roots
  5022.  
  5023.        poly_cpx_root(struct complex * r, double * c, struct polyx * a,
  5024.           struct polyx * temp, struct polyx * temp2,
  5025.           struct polyx * temp3);
  5026.        poly_cpx_root_e(struct complex * r, double * c, struct polyx * a,
  5027.           struct polyx * temp, struct polyx * temp2,
  5028.           struct polyx * temp3);
  5029.  
  5030.  
  5031.        Finds all roots of the polynomial a, and returns them in r.
  5032.        r and c must point to arrays of at least a.order elements.
  5033.  
  5034.        The condition numbers of the roots are returned in c. See
  5035.        poly_cpx_root for a discussion of the condition number.
  5036.  
  5037.        temp, temp2, and temp3 are used as a work area.
  5038.  
  5039.  
  5040.        Example:
  5041.  
  5042.        struct polyx a, temp, temp2, temp3;
  5043.        struct complex r[VP_POLYNOMIAL_MAX_ORDER];
  5044.        double c[VP_POLYNOMIAL_MAX_ORDER];
  5045.        short i;
  5046.  
  5047.        main()
  5048.            {
  5049.            /* Initialize complex polynomial a here. */
  5050.            if (i = poly_cpx_roots_e(r, c, &a, temp, temp2, temp3))
  5051.               {
  5052.               /* Handle error i here */
  5053.               }
  5054.            /* We have now found the roots of a */
  5055.            }
  5056.  
  5057.  
  5058.            Possible Errors:
  5059.                          VP_ILL_CONDITIONED       some c[i] > 1010
  5060.                          VP_PARAM_ERROR           a.order = 0
  5061.                          VP_NO_CONVERGENCE
  5062.                          VP_ACC_PLOSS             there was weak convergence
  5063.  
  5064.            Lagurre's Method with deflation and root polishing is used
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.  
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.                                                                  Poly cpx - 12
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.        poly cpx sub
  5088.  
  5089.        poly_cpx_sub(struct polyx * r, struct polyx * a, struct polyx * b);
  5090.        poly_cpx_sub_e(struct polyx * r, struct polyx * a, struct polyx * b);
  5091.  
  5092.        Sets complex polynomial r = complex polynomial a - complex polynomial
  5093.        b.
  5094.        r.order becomes max(a.order, b.order).
  5095.  
  5096.  
  5097.        Example:
  5098.  
  5099.        struct polyx r;
  5100.        struct polyx a;
  5101.        struct polyx b;
  5102.        short i;
  5103.  
  5104.        main()
  5105.            {
  5106.            /* Initialize complex polynomials a and b here */
  5107.            if (i = poly_cpx_sub_e(&r, &a, &b))
  5108.               {
  5109.               /* Handle error i here */
  5110.               }
  5111.            /* r = a - b */
  5112.            }
  5113.  
  5114.  
  5115.        Possible errors:
  5116.                     VP_OVERFLOW    attempted to make r.order too large.
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.  
  5125.  
  5126.  
  5127.  
  5128.  
  5129.  
  5130.  
  5131.  
  5132.  
  5133.  
  5134.  
  5135.  
  5136.  
  5137.  
  5138.  
  5139.  
  5140.  
  5141.  
  5142.  
  5143.  
  5144.  
  5145.                                                                  Poly cpx - 13
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.        poly cpx zero
  5154.  
  5155.        poly_cpx_zero(struct polyx * r);
  5156.        poly_cpx_zero_e(struct polyx * r);
  5157.  
  5158.        Sets complex polynomial r = 0.
  5159.        r.order becomes 0, co[0] becomes 0.
  5160.  
  5161.  
  5162.        Example:
  5163.  
  5164.        struct polyx r;
  5165.        short i;
  5166.  
  5167.        main()
  5168.            {
  5169.            if (i = poly_cpx_zero_e(&r))
  5170.               {
  5171.               /* Handle error i here */
  5172.               }
  5173.            /* r = 0 */
  5174.            }
  5175.  
  5176.  
  5177.        Possible errors:
  5178.                     NONE
  5179.  
  5180.  
  5181.  
  5182.  
  5183.  
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.                                                                  Poly cpx - 14
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.        Sorting and Searching
  5223.  
  5224.        A sort routine, and two binary search routines are provided. They are
  5225.        intended to complement the standard routines of the C library, which
  5226.        are intended to operate on structures. The VectorPro routines operate
  5227.        on data in double arrays.
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.  
  5247.  
  5248.  
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.                                                                       Sort - 1
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.        binary search
  5286.  
  5287.        binary_search(double * x, short n, double xi);
  5288.        binary_search_e(double * x, short n, double xi);
  5289.  
  5290.        Performs a binary search for the value xi on a sorted array of n
  5291.        doubles pointed to by x.
  5292.        The index of xi is returned as the function value. -1 is returned if
  5293.        xi could not be found.
  5294.  
  5295.  
  5296.        Example:
  5297.  
  5298.        double x[100];
  5299.        double xi;
  5300.        short i;
  5301.  
  5302.        main()
  5303.            {
  5304.            /* Load and sort the array x, initialize xi */
  5305.            if ((i = binary_search_e(x, 100, xi)) == -1)
  5306.               {
  5307.               /* Search failed. Handle the error. */
  5308.               }
  5309.            /* i = the index of xi */
  5310.            }
  5311.  
  5312.  
  5313.        Possible Errors:
  5314.                     -1             Search failed
  5315.  
  5316.  
  5317.  
  5318.  
  5319.  
  5320.  
  5321.  
  5322.  
  5323.  
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.                                                                       Sort - 2
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.        binary search i
  5352.  
  5353.        binary_search_i(double * x, short n, double xi);
  5354.        binary_search_i_e(double * x, short n, double xi);
  5355.  
  5356.        Performs a binary search for the value xi on a sorted array of n
  5357.        doubles pointed to by x.
  5358.        The index of xi is returned as the function value. If xi could not be
  5359.        found, but xi is within the table's range of values, the index of the
  5360.        largest element smaller than xi is returned. -1 is returned if xi is
  5361.        less than x[0] or greater than x[n-1].
  5362.  
  5363.        binary_search_i is useful for certain situations where you want to
  5364.        know where xi would go if it was in the table. You may want to know
  5365.        where to add it, or find the closest value, etc.
  5366.  
  5367.        Example:
  5368.  
  5369.        double x[100], xi;
  5370.        short i;
  5371.  
  5372.        main()
  5373.            {
  5374.            /* Load and sort the array x, initialize xi */
  5375.            if ((i = binary_search_i_e(x, 100, xi)) == -1)
  5376.               {
  5377.               /* Search failed. Handle the error. */
  5378.               if (xi < x[0])
  5379.                  {
  5380.                  /* xi is too small for this table */
  5381.                  }
  5382.               else
  5383.                  {
  5384.                  /* xi is too large for this table */
  5385.                  }
  5386.               }
  5387.            /* i = the index of xi */
  5388.            if (xi == x[i])
  5389.               {
  5390.               /* There was an exact match */
  5391.               }
  5392.            else
  5393.               {
  5394.               /* xi goes between elements i and i+1 */
  5395.               }
  5396.            }
  5397.  
  5398.        Possible Errors:
  5399.                     -1             Search failed
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.  
  5409.                                                                       Sort - 3
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.        heap sort
  5418.  
  5419.        heap_sort(double * x, short n, double ** others, short n_others);
  5420.        heap_sort_e(double * x, short n, double ** others, short n_others);
  5421.  
  5422.        heap_sort is used to sort data stored in arrays of double. To sort
  5423.        structures, use the library routine qsort. heap_sort will also, if you
  5424.        wish, rearrange other arrays to keep their elements associated with
  5425.        the corresponding elements of the sorted array.
  5426.  
  5427.        x is the array to sort.
  5428.        n is the number of elements in x.
  5429.        others is a pointer to an array of pointers containing n_others
  5430.        elements. Each array pointed to by others is also rearranged.
  5431.  
  5432.  
  5433.        Example:
  5434.  
  5435.        double x[100], o1[100], o2[100], o3[100];
  5436.        double * others[3] = {o1, o2, o3};
  5437.        short i;
  5438.  
  5439.        main()
  5440.            {
  5441.            /* Read in arrays of data x, o1, o2, o3 */
  5442.            if (i = heap_sort_e(x, 100, others, 3))
  5443.               {
  5444.               /* Handle error i here */
  5445.               }
  5446.            /* The 4 columns of data are now sorted by column x */
  5447.            }
  5448.  
  5449.        Possible errors:
  5450.                     NONE
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.  
  5473.  
  5474.  
  5475.                                                                       Sort - 4
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.  
  5484.  
  5485.  
  5486.        Trigonometry
  5487.  
  5488.        One trigonometry routine is provided: sincos. It exists because you
  5489.        often need both the sine and cosine of the same angle. sincos can
  5490.        calculate both at once almost as fast as the normal sin and cos
  5491.        functions can calculate a single one.
  5492.  
  5493.  
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500.  
  5501.  
  5502.  
  5503.  
  5504.  
  5505.  
  5506.  
  5507.  
  5508.  
  5509.  
  5510.  
  5511.  
  5512.  
  5513.  
  5514.  
  5515.  
  5516.  
  5517.  
  5518.  
  5519.  
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.                                                                       Trig - 1
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.        sincos
  5550.  
  5551.        sincos(double theta, double * s, double * c);
  5552.        sincos_e(double theta, double * s, double * c);
  5553.  
  5554.        sincos is used to calculate the sine and cosine of an angle, theta,
  5555.        simulataneously. It is provided simply for speed. Using sincos is
  5556.        almost twice as fast as making as call to sin() and then to cos(). The
  5557.        sine is returned via s and the cosine via c.
  5558.  
  5559.  
  5560.        Example:
  5561.  
  5562.        double c, s, theta, r, x, y;
  5563.        short i;
  5564.  
  5565.        main()
  5566.            {
  5567.            theta = 0.4;
  5568.            r = 10.0;
  5569.            if (i = sincos_e(theta, &s, &c))
  5570.               {
  5571.               /* Handle error i here */
  5572.               }
  5573.            x = c*r;
  5574.            y = s*r;
  5575.            /* Polar coordinates (r,theta) now converted to cartesian
  5576.            coordinates (x,y) */
  5577.            }
  5578.  
  5579.  
  5580.        Possible Errors:
  5581.                     NONE
  5582.  
  5583.  
  5584.  
  5585.  
  5586.  
  5587.  
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.  
  5606.  
  5607.                                                                       Trig - 2
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.  
  5616.  
  5617.  
  5618.  
  5619.        VECTOR Operations
  5620.  
  5621.        Vectors are assumed to be stored in arrays of double, starting at
  5622.        element zero. Pass vectors to the functions by passing a pointer to
  5623.        double pointed at the zero element of the array. If you prefer, you
  5624.        may write your main program to begin at element one. If so, just pass
  5625.        a pointer to element one where a pointer to a vector is expected.
  5626.  
  5627.        Examples:
  5628.  
  5629.        Assuming the zero elements are used:
  5630.  
  5631.        double v[3];
  5632.        short i;
  5633.        if ((i = vec_zero(v, 3)) != 0)
  5634.           {
  5635.           /* Recover from error i here ... */
  5636.           }
  5637.        /* Vector v has now been set to zero. */
  5638.  
  5639.  
  5640.        Assuming vectors begin with element one:
  5641.  
  5642.        double v[4];
  5643.        short i;
  5644.        if ((i = vec_zero(&v[1], 3)) != 0)
  5645.           {
  5646.           /* Recover from error i here ... */
  5647.           }
  5648.        /* Vector v has now been set to zero. */
  5649.  
  5650.        The remaining examples in this chapter will assume that the zero
  5651.        element of all vectors is used. Unless otherwise specified, all
  5652.        routines accept vectors with any number of dimensions.
  5653.  
  5654.  
  5655.  
  5656.        >
  5657.  
  5658.  
  5659.  
  5660.  
  5661.  
  5662.  
  5663.  
  5664.  
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.                                                                    Vectors - 1
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.        vec add
  5681.  
  5682.        vec_add(double * r, double * a, double * b, short n);
  5683.        vec_add_e(double * r, double * a, double * b, short n);
  5684.  
  5685.        Sets the vector r equal to the sum of vectors a and b. All vectors are
  5686.        assumed to have n elements. If the pointer r equals the pointer a or
  5687.        b, the function will still work correctly.
  5688.  
  5689.  
  5690.        Example:
  5691.  
  5692.        double a[3], b[3], r[3];
  5693.        short i;
  5694.        ...
  5695.        if ((i = vec_add_e(r, a, b, 3) != 0)
  5696.           {
  5697.           /* Recover from error i here */
  5698.           }
  5699.  
  5700.  
  5701.  
  5702.        Possible errors:
  5703.  
  5704.                NONE
  5705.  
  5706.  
  5707.  
  5708.  
  5709.  
  5710.  
  5711.  
  5712.  
  5713.  
  5714.  
  5715.  
  5716.  
  5717.  
  5718.  
  5719.  
  5720.  
  5721.  
  5722.  
  5723.  
  5724.  
  5725.  
  5726.  
  5727.  
  5728.  
  5729.  
  5730.  
  5731.  
  5732.  
  5733.  
  5734.  
  5735.  
  5736.  
  5737.  
  5738.  
  5739.                                                                    Vectors - 2
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.        vec angle
  5748.  
  5749.        vec_angle(double * theta, double * a, double * b, short n);
  5750.        vec_angle_e(double * theta, double * a, double * b, short n);
  5751.  
  5752.        Sets the scalar *theta equal to the angle, in radians, between two
  5753.        vectors a and b. All vectors are assumed to have n elements.
  5754.  
  5755.  
  5756.        Example:
  5757.  
  5758.        double a[3], b[3], theta;
  5759.        short i;
  5760.        ...
  5761.        if ((i = vec_angle_e(theta, a, b, 3) != 0)
  5762.           {
  5763.           /* Recover from error i here */
  5764.           }
  5765.  
  5766.  
  5767.  
  5768.        Possible errors:
  5769.  
  5770.                DIV_BY_ZERO         Either a or b is a zero vector
  5771.  
  5772.  
  5773.  
  5774.  
  5775.  
  5776.  
  5777.  
  5778.  
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.                                                                    Vectors - 3
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.        vec copy
  5814.  
  5815.        vec_copy(double * r, double * a, short n);
  5816.        vec_copy_e(double * r, double * a, short n);
  5817.  
  5818.        Sets the vector r equal to the vector a. All vectors are assumed to
  5819.        have n elements.
  5820.  
  5821.  
  5822.        Example:
  5823.  
  5824.        double a[3], r[3];
  5825.        short i;
  5826.        ...
  5827.        if ((i = vec_copy_e(r, a, 3) != 0)
  5828.           {
  5829.           /* Recover from error i here */
  5830.           }
  5831.  
  5832.  
  5833.  
  5834.        Possible errors:
  5835.  
  5836.                NONE
  5837.  
  5838.  
  5839.  
  5840.  
  5841.  
  5842.  
  5843.  
  5844.  
  5845.  
  5846.  
  5847.  
  5848.  
  5849.  
  5850.  
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.  
  5867.  
  5868.  
  5869.  
  5870.  
  5871.                                                                    Vectors - 4
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.        vec crossprod
  5880.  
  5881.        vec_crossprod(double * r, double * a, double * b);
  5882.        vec_crossprod_e(double * r, double * a, double * b);
  5883.  
  5884.        Sets the vector r equal to the cross product of vectors a and b. All
  5885.        vectors are assumed to have 3 elements.
  5886.  
  5887.  
  5888.        Example:
  5889.  
  5890.        double a[3], b[3], r[3];
  5891.        short i;
  5892.        ...
  5893.        if ((i = vec_crossprod_e(r, a, b) != 0)
  5894.           {
  5895.           /* Recover from error i here */
  5896.           }
  5897.  
  5898.  
  5899.  
  5900.        Possible errors:
  5901.  
  5902.                NONE
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.  
  5935.  
  5936.  
  5937.                                                                    Vectors - 5
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.  
  5945.        vec dotprod
  5946.  
  5947.        vec_dotprod(double * d, double * a, double * b, short n);
  5948.        vec_dotprod_e(double * d, double * a, double * b, short n);
  5949.  
  5950.        Sets the scalar *d equal to the dot product of vectors a and b. All
  5951.        vectors are assumed to have n elements.
  5952.  
  5953.  
  5954.        Example:
  5955.  
  5956.        double a[3], b[3], theta;
  5957.        short i;
  5958.        ...
  5959.        if ((i = vec_dotprod_e(&d, a, b, 3) != 0)
  5960.           {
  5961.           /* Recover from error i here */
  5962.           }
  5963.  
  5964.  
  5965.  
  5966.        Possible errors:
  5967.  
  5968.                NONE
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.  
  5983.  
  5984.  
  5985.  
  5986.  
  5987.  
  5988.  
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.  
  6001.  
  6002.  
  6003.                                                                    Vectors - 6
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.  
  6011.        vec gendotprod
  6012.  
  6013.        vec_gendotprod(double * d, char * a, char * b, short n, short a_inc,
  6014.                       short b_inc);
  6015.        vec_gendotprod_e(double * d, char * a, char * b, short n, short a_inc,
  6016.                       short b_inc);
  6017.  
  6018.        Sets the scalar *d equal to the dot product of vectors a and b. All
  6019.        vectors are assumed to have n elements. In this function, the vectors
  6020.        a and b are assumed to be elements of larger structures. The pointers
  6021.        passed are pointers to the vector elements in the first structure of
  6022.        each structure array. a_inc and b_inc are the sizes of the structures.
  6023.        They are needed to find the vector elements in the following
  6024.        structures.
  6025.  
  6026.  
  6027.        Example:
  6028.  
  6029.        struct my_data
  6030.           {
  6031.           short q;
  6032.           double number;
  6033.           char m[20];
  6034.           }
  6035.        struct my_data a[50];
  6036.        struct my_data b[50];
  6037.        short i;
  6038.        double d;
  6039.        ...
  6040.        if ((i = vec_gendotprod_e(&d, (char *) a[0].number,
  6041.           (char *) b[0].number, 50, sizeof(struct my_data),
  6042.           sizeof(struct my_data)) != 0)
  6043.           {
  6044.           /* Recover from error i here */
  6045.           }
  6046.  
  6047.  
  6048.  
  6049.        Possible errors:
  6050.  
  6051.                NONE
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.  
  6067.  
  6068.  
  6069.                                                                    Vectors - 7
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.        vec magnitude
  6078.  
  6079.        vec_magnitude(double * mag, double * a, short n);
  6080.        vec_magnitude_e(double * mag, double * a, short n);
  6081.  
  6082.        Sets the scalar *mag equal to the magnitude of vector a. Vector a is
  6083.        assumed to have n elements.
  6084.  
  6085.  
  6086.        Example:
  6087.  
  6088.        double a[6], mag;
  6089.        short i;
  6090.        ...
  6091.        if ((i = vec_magnitude_e(mag, a, 6) != 0)
  6092.           {
  6093.           /* Recover from error i here */
  6094.           }
  6095.  
  6096.  
  6097.  
  6098.        Possible errors:
  6099.  
  6100.                NONE
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.  
  6110.  
  6111.  
  6112.  
  6113.  
  6114.  
  6115.  
  6116.  
  6117.  
  6118.  
  6119.  
  6120.  
  6121.  
  6122.  
  6123.  
  6124.  
  6125.  
  6126.  
  6127.  
  6128.  
  6129.  
  6130.  
  6131.  
  6132.  
  6133.  
  6134.  
  6135.                                                                    Vectors - 8
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.        vec scalar
  6144.  
  6145.        vec_scalar(double * r, double * a, double * x, short n);
  6146.        vec_scalar_e(double * r, double * a, double * x, short n);
  6147.  
  6148.        Sets the vector r equal to the product of scalar x times vector a. All
  6149.        vectors are assumed to have n elements. If the pointer r equals the
  6150.        pointer a, the function will still work correctly.
  6151.  
  6152.  
  6153.        Example:
  6154.  
  6155.        double a[4], r[4];
  6156.        short i;
  6157.        ...
  6158.        if ((i = vec_scalar_e(r, a, 77.2, 4) != 0)
  6159.           {
  6160.           /* Recover from error i here */
  6161.           }
  6162.  
  6163.  
  6164.  
  6165.        Possible errors:
  6166.  
  6167.                NONE
  6168.  
  6169.  
  6170.  
  6171.  
  6172.  
  6173.  
  6174.  
  6175.  
  6176.  
  6177.  
  6178.  
  6179.  
  6180.  
  6181.  
  6182.  
  6183.  
  6184.  
  6185.  
  6186.  
  6187.  
  6188.  
  6189.  
  6190.  
  6191.  
  6192.  
  6193.  
  6194.  
  6195.  
  6196.  
  6197.  
  6198.  
  6199.  
  6200.  
  6201.                                                                    Vectors - 9
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.  
  6209.        vec sub
  6210.  
  6211.        vec_sub(double * r, double * a, double * b, short n);
  6212.        vec_sub_e(double * r, double * a, double * b, short n);
  6213.  
  6214.        Sets the vector r equal to vector a minus vector b. All vectors are
  6215.        assumed to have n elements. If the pointer r equals the pointer a or
  6216.        b, the function will still work correctly.
  6217.  
  6218.  
  6219.        Example:
  6220.  
  6221.        double a[3], b[3], r[3];
  6222.        short i;
  6223.        ...
  6224.        if ((i = vec_sub_e(r, a, b, 3) != 0)
  6225.           {
  6226.           /* Recover from error i here */
  6227.           }
  6228.  
  6229.  
  6230.  
  6231.        Possible errors:
  6232.  
  6233.                NONE
  6234.  
  6235.  
  6236.  
  6237.  
  6238.  
  6239.  
  6240.  
  6241.  
  6242.  
  6243.  
  6244.  
  6245.  
  6246.  
  6247.  
  6248.  
  6249.  
  6250.  
  6251.  
  6252.  
  6253.  
  6254.  
  6255.  
  6256.  
  6257.  
  6258.  
  6259.  
  6260.  
  6261.  
  6262.  
  6263.  
  6264.  
  6265.  
  6266.  
  6267.                                                                   Vectors - 10
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.        vec total
  6276.  
  6277.        vec_total(double * t, short n, short n_inputs, double * a,
  6278.           double a_factor, ...);
  6279.        vec_total_e(double * t, short n, short n_inputs, double * a,
  6280.           double a_factor, ...);
  6281.  
  6282.        Adds up a list of up to six vectors times a scalar factor, and adds it
  6283.        all to the vector t. Each vector has n elements. n_inputs may range
  6284.        from 1 to 6.
  6285.  
  6286.        t = t + a_factor*a [+b_factor*b + ... + f_factor*f]
  6287.  
  6288.        The function is limited to six input vectors because of the methods
  6289.        used in optimizing the assembler version of the function. If you need
  6290.        to add more than six vectors, use several calls to vec_total.
  6291.  
  6292.        Example:
  6293.  
  6294.        double p[3], v[3], a[3];
  6295.        short i;
  6296.        ...
  6297.        if ((i = vec_total_e(p, 3, 2, v, .01, a, .00005) != 0)
  6298.           {
  6299.           /* Recover from error i here */
  6300.           }
  6301.        /* p = p + vt + at2/2   where t = 0.01     */
  6302.  
  6303.  
  6304.  
  6305.        Possible errors:
  6306.  
  6307.                PARAM_ERROR         n_inputs was out of range
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.  
  6332.  
  6333.                                                                   Vectors - 11
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.        vec unit
  6342.  
  6343.        vec_unit(double * r, double * a, short n);
  6344.        vec_unit_e(double * r, double * a, short n);
  6345.  
  6346.        Sets the vector r equal to the unit vector parallel to vector a. All
  6347.        vectors are assumed to have n elements.
  6348.  
  6349.  
  6350.        Example:
  6351.  
  6352.        double a[3], r[3];
  6353.        short i;
  6354.        ...
  6355.        if ((i = vec_unit_e(r, a, 3) != 0)
  6356.           {
  6357.           /* Recover from error i here */
  6358.           }
  6359.  
  6360.  
  6361.  
  6362.        Possible errors:
  6363.  
  6364.                DIV_BY_ZERO         vector a was all zeroes
  6365.  
  6366.  
  6367.  
  6368.  
  6369.  
  6370.  
  6371.  
  6372.  
  6373.  
  6374.  
  6375.  
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394.  
  6395.  
  6396.  
  6397.  
  6398.  
  6399.                                                                   Vectors - 12
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.  
  6407.        vec zero
  6408.  
  6409.        vec_zero(double * r, short n);
  6410.        vec_zero_e(double * r, short n);
  6411.  
  6412.        Sets the vector r equal to zero. r is assumed to have n elements.
  6413.  
  6414.  
  6415.        Example:
  6416.  
  6417.        double r[10];
  6418.        short i;
  6419.        ...
  6420.        if ((i = vec_zero_e(r, 10) != 0)
  6421.           {
  6422.           /* Recover from error i here */
  6423.           }
  6424.  
  6425.  
  6426.  
  6427.        Possible errors:
  6428.  
  6429.                NONE
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.  
  6463.  
  6464.  
  6465.                                                                   Vectors - 13
  6466.  
  6467.  
  6468.  
  6469.